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ABSTRACT:  The  two-dimensional  (2-D)  circulation  model  M2D,  developed  under  the  Coastal  Inlets  Research 
Program  conducted  at  the  U.S.  Army  Engineer  Research  and  Development  Center,  Coastal  and  Hydraulics  Labora¬ 
tory,  has  been  designed  for  local  applications,  primarily  at  inlets,  the  nearshore,  and  bays.  M2D  is  computationally 
efficient,  easy  to  set  up,  and  has  features  required  for  many  coastal  engineering  applications  including  robust  flood¬ 
ing  and  drying,  wind-speed  dependent  (time-varying)  wind-drag  coefficient,  variably-spaced  bottom-friction  coeffi¬ 
cient,  time-  and  space- varying  wave-stress  forcing,  efficient  grid  storage  in  memory,  two  hot-start  options,  and  the 
convenience,  through  control  statements,  of  independently  turning  on  or  off  the  advective  terms  and  mixing  terms. 

If  wave  information  is  available,  such  as  through  coupling  with  the  STeady  state  spectral  WAVE  model  STWAVE, 
M2D  will  calculate  wave  friction  and  wave  mixing.  M2D  can  be  coupled  to  regional  circulation  models  through 
boundary  conditions  providing  flexibility  for  large-scale  applications  and  connectivity  between  models. 

A  graphical  interface  for  M2D  has  been  implemented  within  the  Surface-Water  Modeling  System  (SMS)  Versions  8.1 
and  higher.  Features  of  the  M2D  interface  are  grid  development,  control  file  specification,  model  runs,  post-processing  of 
results,  and  visualization.  M2D  can  be  driven  by  larger-domain  circulation  models,  such  as  ADCIRC,  through  boundary 
specification  capabilities  contained  within  the  SMS.  The  Steering  Module  in  SMS  provides  an  automated  means  of  cou¬ 
pling  of  M2D  with  STWAVE,  which  is  convenient  for  projects  that  require  wave-stress  forcing  for  M2D  as  well  as  wave 
friction  and  mixing  owing  to  breaking  waves.  The  Steering  Module  allows  the  user  to  choose  from  seven  possible  coupling 
combinations,  providing  flexibility  in  conducting  simulations  of  wave-driven  currents  and  wave-current  interaction. 
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Preface 


Development  of  the  tidal  and  nearshore  circulation  model  M2D  was 
conducted  as  part  of  activities  of  the  Coastal  Inlets  Research  Program  (CIRP), 
Inlet  Modeling  System  (IMS)  work  unit.  CIRP  is  administered  at  the  U.S.  Army 
Engineer  Research  and  Development  Center  (ERDC),  Coastal  and  Hydraulics 
Laboratory  (CHL)  under  the  Navigation  Systems  Program  for  Headquarters,  U.S. 
Army  Corps  of  Engineers  (HQUSACE).  Mr.  Barry  W.  Holliday  is  HQUSACE 
lead  technical  monitor  for  CIRP.  Dr.  Sandra  K.  Knight,  CHL,  is  Technical 
Director  for  the  Navigation  Systems  Program.  Dr.  Nicholas  C.  Kraus,  Senior 
Scientists  Group,  CHL,  is  CIRP  Program  Manager,  and  Ms.  Mary  A.  Cialone, 
Coastal  Processes  Branch,  CHL,  is  IMS  work  unit  Principal  Investigator. 

The  mission  of  CIRP  is  to  conduct  applied  research  to  improve  USACE 
capability  to  manage  federally  maintained  inlets,  which  exist  on  all  coasts  of  the 
United  States  (including  the  Atlantic  Ocean,  Gulf  of  Mexico,  Pacific  Ocean,  and 
Great  Lakes  regions).  CIRP  objectives  are  to  (a)  make  management  of  channels 
-  the  design,  maintenance,  and  operation  -  more  effective  to  reduce  the  cost  of 
dredging,  and  (b)  preserve  the  adjacent  beaches  in  a  systems  approach  that  treats 
the  inlet  and  beach  together.  To  achieve  these  objectives,  CIRP  is  organized  in 
work  units  conducting  research  and  development  in  hydrodynamic,  sediment 
transport,  and  morphology  change  modeling;  navigation  channels  and  adjacent 
beaches;  inlet  scour  and  jetties;  laboratory  and  field  investigations;  and 
technology  transfer. 

This  report  was  prepared  by  Dr.  Adele  Militello,  Coastal  Analysis  LLC, 

Dr.  Christopher  W.  Reed,  URS  Corporation,  Dr.  Alan  K.  Zundel,  Environmental 
Modeling  Research  Laboratory,  Brigham  Young  University,  and  Dr.  Nicholas  C. 
Kraus,  CHL.  Dr.  Militello  was  Principal  Investigator  for  M2D  model 
development.  Dr.  Frank  Buonaiuto,  State  University  of  New  York  at  Stony 
Brook,  Marine  Sciences  Research  Institute,  contributed  to  model  development 
and  testing  for  wave  radiation-stress  implementation.  Work  was  performed 
under  the  general  administrative  supervision  of  Mr.  Thomas  W.  Richardson, 
Director,  CHL,  and  Dr.  William  D.  Martin,  Deputy  Director,  CHL 

At  the  time  of  publication  of  this  report,  Dr.  James  R.  Houston  was  Director 
of  ERDC,  and  COL  James  R.  Rowan,  EN,  was  Commander  and  Executive 
Director. 
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1  Introduction  to  M2D 


At  coastal  inlets,  water  and  sediment  undergo  complex  motions  by  forcing  at 
many  temporal  and  spatial  scales,  and  with  constraints  imposed  by  the  sea 
bottom  morphology,  jetties,  training  structures,  and  dredging.  Forcing  can 
involve  combinations  of  the  astronomical  and  meteorological  tide,  waves,  wind, 
and  rivers.  Interactions  also  occur  among  waves,  currents,  sediment,  and  the 
bottom  morphology,  which  also  changes  through  time.  Advances  in  numerical 
modeling,  increased  speed  of  desktop  computers,  and  reliable  and  powerful 
interfaces  now  make  calculation  of  morphology  change  at  inlets  feasible. 
Simulation  of  morphology  change  at  inlets  is  an  emerging  area  of  applied 
research  of  interest  to  the  U.S.  Army  Corps  of  Engineers  (USACE)  and  its 
navigation  mission  at  coastal  inlets. 

Because  of  the  wide  range  of  problems  to  be  addressed,  both  basic  and 
applied,  success  in  simulation  of  coastal  inlet  processes  is  expected  to  be  an 
outcome  of  exchange  of  information  among  interdisciplinary  teams.  These  teams 
are  composed  of  coastal  engineers  and  scientists  working  in  government,  private 
industry,  and  academia.  A  system  approach  is  required  that  is  based  on  a 
comprehensive  numerical  model  with  a  code  accessible  to  a  wide  range  of 
researchers.  At  the  same  time,  the  model  should  be  efficient  in  calculation  so 
that  it  may  be  exercised  in  addressing  practical  problems.  Experience  with  a 
variety  of  coastal  inlets  and  engineering  problems  will,  in  turn,  call  for 
improvements  and  advances  in  model  development. 

The  model  M2D  was  developed  under  the  Coastal  Inlets  Research  Program 
(CIRP)  conducted  at  the  U.S,  Army  Engineer  Research  and  Development  Center 
(ERDC),  Coastal  and  Hydraulics  Laboratory  (CHL)  as  one  such  simulation 
model  with  which  to  support  multidisciplinary  research  teams  and  conduct 
practical  projects  at  coastal  inlets.  M2D  is  a  hydrodynamic  model  intended  for 
local  applications,  primarily  at  inlets,  the  nearshore,  and  bays.  M2D  is 
computationally  efficient,  easy  to  set  up,  and  has  features  required  for  many 
coastal  engineering  applications.  M2D  can  be  coupled  to  regional  circulation 
models,  such  as  the  ADvanced  CIRCulation  (ADCIRC)  model  (Luettich  et  al. 
1992),  through  boundary  conditions  (Militello  and  Zundel  2002a,  2002b), 
providing  flexibility  for  large-scale  applications  and  connectivity  between 
models.  At  the  same  time,  the  code  is  accessible  to  CIRP  researchers  with 
expertise  in  areas  other  than  computational  fluid  dynamics,  as  expected  in 
interdisciplinary  teams. 
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Scope  of  Model 

M2D  is  a  finite-difference  numerical  representation  of  the  two-dimensional 
(2-D)  depth-integrated  continuity  and  momentum  equations  of  water  motion. 

The  governing  equations,  finite-difference  approximation,  representation  of 
bottom  and  surface  stresses,  grid  scheme,  boundary  conditions,  other  model 
features,  and  graphical  interface  are  documented  in  this  report.  Cells  are  defined 
on  a  staggered,  rectilinear  grid  and  can  have  constant  or  variable  side  lengths. 
Momentum  equations  are  solved  in  a  time-stepping  manner  first,  followed  by 
solution  of  the  continuity  equation,  in  which  the  updated  velocities  calculated  by 
the  momentum  equations  are  applied. 

For  support  of  engineering  applications,  features  of  the  model  M2D  include 
flooding  and  drying,  wind-speed  dependent  (time-varying)  wind-drag  coefficient, 
variably-spaced  bottom-friction  coefficient,  time-and  space-varying  wave-stress 
forcing,  efficient  grid  storage  in  memory,  two  hot-start  options,  and  the 
convenience,  through  control  statements,  of  independently  turning  on  or  off  the 
advective  terms,  mixing  terms,  and  flooding  and  drying  calculations. 
Additionally,  model  output  is  written  in  formats  convenient  for  importing  into 
commercially  available  plotting  packages.  For  researchers,  the  code  is  readily 
understandable  for  implementation  of  supplemental  algorithms  for  the  wave- 
current  interaction,  and  for  calculating  sediment  transport  and  morphology 
change. 

M2D  has  been  designed  as  a  local-scale  model  that  can  be  easily  and  quickly 
applied  to  engineering  projects.  The  model  has  been  developed  to  maximize 
flexibility  in  grid  specifications  and  model  forcing.  For  example,  if  forcing  by  a 
water  surface  elevation  time  series  is  prescribed  as  a  boundary  condition,  the 
time  interval  between  values  in  the  time  series  does  not  have  to  be  constant. 

Thus,  if  values  were  being  supplied  from  a  water  level  gauge  and  the  sampling 
rate  was  modified,  the  measurements  could  be  prescribed  as  forcing  without  sub¬ 
sampling  the  data  set. 


Implementation  within  Surface-Water  Modeling 
System 

A  graphical  interface  for  M2D  has  been  implemented  within  the  Surface- 
Water  Modeling  System  (SMS)  Versions  8.1  and  higher  (Zundel  2000).  Features 
of  the  M2D  interface  are  grid  development,  control  file  specification,  model  runs, 
post-processing  of  results,  and  visualization.  SMS  provides  flexibility  in  grid 
generation  and  modification  by  providing  tools  to  assign  bathymetric  data  sets 
for  interpolation  to  the  M2D  grid,  manually  modify  depths  and  friction 
coefficients,  adjust  cell  sizes,  and  insert  or  delete  cells.  Variably  spaced  grids 
can  be  easily  developed  by  applying  tools  that  spatially  scale  the  cell  sizes  over 
user-defined  extents.  SMS  provides  dialogs  for  specification  of  boundary 
conditions.  For  some  boundary  types,  forcing  information  can  be  input  manually 
from  within  SMS,  or  predefined  information  can  be  read  in  from  files.  A  model 


2 


Chapter  1  Introduction  to  M2D 


control  dialog  provides  the  user  with  a  convenient  interface  for  specifying  timing 
control,  model  options,  wind  and  wave  forcing,  and  output  options. 

M2D  can  be  driven  by  larger-domain  circulation  models,  such  as  ADCIRC, 
through  boundary  specification  capabilities  contained  within  the  SMS.  The 
boundary  conditions  dialog  provides  access  to  solutions  from  larger-domain 
models  that  can  be  extracted  and  mapped  to  M2D  boundaries.  The  user  can 
decide  whether  to  specify  water  surface  elevation  or  a  combination  of  water 
surface  elevation  and  velocity  as  boundary  forcing  for  M2D.  This  capability 
provides  M2D  with  boundary  conditions  that  preserve  tidal  phase  and  other 
variations  calculated  by  the  larger-scale  model. 

SMS  also  provides  an  automated  means  of  coupling  of  M2D  with  the  STeady 
state  spectral  WAVE  model  STWAVE  (Smith  et  al.  1 999,  200 1 )  through  the 
Steering  Module,  which  is  convenient  for  projects  that  require  wave-stress 
forcing  for  M2D.  The  Steering  Module  allows  the  user  to  choose  from  seven 
possible  coupling  combinations,  providing  flexibility  in  conducting  simulations 
of  wave-driven  currents  and  wave-current  interaction. 


Studies  with  M2D 

M2D  was  developed  and  tested  in  basic  and  applied  studies  covering  a  wide 
range  of  bathymetric  configurations,  forcing,  and  project  goals.  Summaries  of 
selected  applications  are  provided  to  familiarize  users  with  model  capabilities 
and  to  establish  model  history. 

M2D  was  first  applied  to  investigate  hydrodynamic  responses  to  proposed 
engineering  projects  on  the  Texas  coast.  Changes  in  circulation  patterns  in  the 
Upper  Laguna  Madre  and  exchange  of  water  with  the  Gulf  of  Mexico  were 
calculated  for  proposed  causeway  modifications  designed  to  improve  evacuation 
safety  (Brown  et  al.  1995a,  1995b,  1995c).  In  an  investigation  of  a  proposed  new 
inlet  called  the  Southwest  Comer  Cut  that  would  connect  East  Matagorda  Bay  to 
the  Colorado  River  Navigation  Channel  (CRNC),  M2D  was  applied  to  calculate 
velocity  changes  in  the  CRNC  and  Gulf  Intracoastal  Waterway  and  to  determine 
whether  the  new  inlet  would  promote  closure  of  Mitchell’s  Cut  (Kraus  and 
Militello  1996;  Militello  and  Kraus  1998;  Kraus  and  Militello  1999). 

In  a  scientific  study  of  the  hydrodynamics  of  Baffin  Bay,  TX,  M2D  was 
applied  to  calculate  the  wind-driven  circulation  and  setup/setdown  in  the  non- 
tidal  bay  (Militello  1998,  2000).  Model  calculations  also  determined  the 
contributions  of  nonlinear  terms  in  the  governing  equations  to  harmonics  of  the 
oscillatory  wind  (sea  breeze)  forcing  in  Baffin  Bay  (Militello  1998;  Militello  and 
Kraus  2001). 

In  a  channel  infilling  study  for  Bay  Center,  WA,  M2D  calculated  current 
velocity  over  a  1 -month  time  interval  from  which  bed  elevation  changes  were 
computed  (Militello  2002;  Militello  et  al.  2002).  The  Bay  Center  application  also 
demonstrated  successful  coupling  of  M2D  with  ADCIRC.  This  success, 


Chapter  1  Introduction  to  M2D 


3 


combined  with  CIRP  goals,  led  to  the  development  of  the  automated  M2D  and 
ADCIRC  (or  other  larger-domain  model)  coupling  capability  within  the  SMS 
(Militello  and  Zundel  2002a;  Militello  and  Zundel  2002b). 


As  part  of  the  CIRP  program  to  assure  model  reliability,  M2D  calculated  tide 
and  wave-driven  currents  at  an  idealized  inlet  and  ebb  shoal  for  fair  weather  and 
storm  waves  (Militello  and  Kraus  2003).  Interactions  between  wave-driven 
currents  and  the  ebb  jet  varied,  depending  on  the  relative  strength  of  the  two 
current  sources.  For  storm  waves,  calculated  alongshore  velocities  were  stronger 
and  the  surf  zone  was  wider  and  further  from  shore,  as  compared  to  the  fair 
weather  waves.  This  study  demonstrated  coupling  of  M2D  and  STWAVE, 
formally  described  in  this  volume  and  Militello  and  Zundel  (2003),  and  correct 
trends  in  sediment  transport  and  morphology  change  that  are  presently  under 
testing  in  M2D. 


Report  Contents 

This  report  provides  documentation  for  M2D  and  instruction  on  development 
of  an  M2D  project  within  the  SMS.  Description  of  the  model  consists  of 
hydrodynamics  only;  sediment  transport  and  morphology  change  are  under 
development  and  will  be  described  in  future  M2D  technical  reports.  Chapter  2 
gives  the  governing  equations  solved  in  the  model.  Chapter  3  describes  the 
finite-difference  approximations  and  defines  the  cell  numbering  method. 

Chapter  4  describes  the  types  of  boundary  conditions  available  in  M2D. 

Chapter  5  provides  descriptions  of  model  features.  Chapter  6  describes  the  SMS 
interface  for  M2D  and  provides  guidance  for  project  development.  Chapter  7 
provides  information  on  model  setup  and  file  structure. 

Appendices  supplement  the  main  text  and  contain  more  detailed  and 
auxiliary  information.  Appendix  A  gives  example  input  and  output  files. 
Appendix  B  provides  references  for  M2D  development  and  applications. 
Appendices  C  through  F  describe  results  of  numerical  model  integrity  tests. 
Appendix  G  demonstrates  the  wave-adjusted  boundary  condition,  which  modifies 
prescribed  boundary  condition  values  for  the  presence  of  wave  forcing. 

Appendix  H  compares  calculated  and  measured  longshore  currents  from 
laboratory  experiments. 
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Chapter  1  Introduction  to  M2D 


2  Governing  Equations 


M2D  solves  the  2-D,  depth-integrated  continuity  and  momentum  equations 
by  applying  a  flux -based  finite-difference  method.  Velocity  components  in  two 
horizontal  dimensions  are  calculated.  This  chapter  introduces  the  governing 
equations  and  describes  the  respective  terms  and  variables.  Wind  and  bottom 
stress  formulations  are  presented,  as  well  as  implementation  of  wave  stresses. 

The  2-D,  depth-integrated  continuity  and  momentum  equations  solved  by 
M2D  are 

d(/?  +  Tj)  [  dqx  |  dqy  =Q 
dt  dx  dy 


ggx  dm*  ,  H  t  1  djh  +  rjf  =  d_D  dq±+d_D  dq_ , 
dt  dx  dy  2  dx  dx  x  dx  dy  y  dy 


dq  duq  dvq  1  d{h  +  x\f 

dt  dx  dy  2  dy 


dx  dy  y 


dy 


fily  T by  +  T wy  +  T Sy 


(2) 


(3) 


where 

h  =  still-water  depth 

T)  =  deviation  of  the  water-surface  elevation  from  the  still-water  level 


t  =  time 


qx  —  flow  per  unit  width  parallel  to  the  x-axis 
qy  =  flow  per  unit  width  parallel  to  the  y-axis 
u  =  depth-averaged  current  velocity  parallel  to  the  x-axis 
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v  =  depth-averaged  current  velocity  parallel  to  the  y-axis 
g  =  acceleration  due  to  gravity 
Dx  =  diffusion  coefficient  for  the  x  direction 
Dy  -  diffusion  coefficient  for  they  direction 
/  =  Coriolis  parameter 
Xbx  =  bottom  stress  parallel  to  the  x-axis 

xby  =  bottom  stress  parallel  to  the  y-axis 
T  =  surface  stress  parallel  to  the  x-axis 
x  =  surface  stress  parallel  to  the  y-axis 
x&  =  wave  stress  parallel  to  the  x-axis 
xs  =  wave  stress  parallel  to  the  y-axis 
Component  velocities  are  related  to  the  flow  rate  per  unit  width  as 

h  +  r\ 

% 

v  —  — — 
h  ~\~x\ 

For  the  situation  without  waves,  bottom  stresses  are  given  by 

v,=Qv|c/| 

where  U  is  the  total  current  speed  and  Cb  is  an  empirical  bottom-stress 
coefficient.  The  total  current  speed  is 

|t/|  =  v/«2+v2 

and  the  bottom-friction  coefficient  is  calculated  by 


(4) 

(5) 

(6) 

(7) 

(8) 
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(9) 


where  C  is  the  Chezy  coefficient  given  by 

nI/6 

C  =  —  (10) 

n 


in  which  R  is  the  hydraulic  radius,  and  n  is  the  Manning  roughness  coefficient. 

In  the  presence  of  waves,  the  bottom  stress  contains  contributions  from  both 
the  quasi-steady  current  (as  from  tide,  wind,  and  surface  waves)  and  the  bottom 
orbital  motion  of  the  waves.  Assessment  of  an  average  bottom  stress  over  the 
period  of  a  surface  wave,  which  requires  numerical  integration,  would  need  to  be 
performed  at  every  grid  point  at  every  time-step,  a  computation-intensive 
operation.  Instead,  here  a  square  wave  approximation  for  the  wave  is  applied, 
which  allows  analytic  estimation  of  the  time  average.  It  is  given  by  the  following 
approximation  for  the  time-averaged  bottom  stress  under  combined  currents  and 
waves  (Nishimura  1988) 


t/  + 


(O 


U.. 


—  cos2  a 


u  + 


3 

u 


\ 


-cos  asm  a 


j 


(11) 


\  =  cb- 


-cosasina  \u  + 


Uwc  + 


to; 


u. 


—sin2  a 


(12) 


in  which  a  is  the  wave  angle  relative  to  the  x-axis,  and  Uwc  and  (Ob  are  given 
by 


Uwc  =-^-|^/|w2  -t-v2  +o)2  +2(MCosa  +  vsina)coi| 
+  yju2  +v2  +co2 -2(MCOsa  +  vsina)coi  j 


coA  = 


off 


7isinh[&(/i-i-r|)] 


(13) 


(14) 


where  cr  is  the  wave  angular  frequency,  H  is  wave  height,  and  k  is  wave  number. 
Surface  wind  stresses  are  given  by 


V-cAlfi  in(e) 

Ph- 


(15) 
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(16) 


x 


wy 


Cd^-W2  cos(0) 

Pw 


where 

Cd  =  wind  drag  coefficient 
pa  =  density  of  air 
pw  =  density  of  water 
W  =  wind  speed 
0  =  wind  direction 

The  convention  for  wind  direction  is  specified  to  be  0  deg  for  wind  from  the  east 
with  angle  increasing  counterclockwise. 

Wave  stresses  are  calculated  from  spatial  gradients  in  radiation  stresses  as 


'-Sx 


Ts,=' 


Pw 


8S  c>0 

XX  _| _ 

dx  dy  j 


1  (dSm+dSm-\ 


dx  dy 


(17) 


(18) 


where  Sxx,  Sxy,  and  Syy  are  wave-driven  radiation  stresses.  Radiation-stress  tensor 
calculations  are  based  on  linear  wave  theory  and  computed  within  STWAVE  or 
other  wave  model.  They  represent  the  summation  of  standard  tensor 
formulations  across  the  defined  spectrum.  For  a  coordinate  system  with  the  x- 
axis  oriented  normal  to  the  shoreline,  the  tensor  components  are  (Smith  et  al. 
2001) 


^  =  JJ^(co,oc) 

p£(ro,a) 


0.5 


wj- 


1+  2k ^  l(cos2a  +  l)-0.5 

sinh2A(/2  +  r|)  J' 


0.5 


2k(h  +  r\) 
sinh  2k(h  +  r\) 


sin  2a 


dctida 


da>da  (19) 


(20) 


dcoda  (21) 


where 
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Sxx,  =  flux  of  shore-normal  momentum 

Sxy  =  of  shore-parallel  momentum,  or  the  shear  component  of  the  radiation 
stress 


Syy  =  flux  of  momentum  alongshore 
E  =  wave  energy  density 

Details  of  the  spectral  wave  calculations  conducted  by  STWAVE  are  described 
in  the  STWAVE  User’s  Guide  (Smith  et  al.  2001). 

Wave  models,  such  as  STWAVE,  generally  define  their  coordinate  systems 
such  that  the  x-axis  is  normal  to  the  shoreline  (positive  x  directed  toward  the 
shore)  and  the  y-axis  is  parallel  to  the  shoreline.  For  M2D  applications,  the 
radiation-stress  tensor  is  rotated  from  the  STWAVE  grid  and  mapped  onto  the 
M2D  grid  by  the  SMS. 

The  Coriolis  parameter  is  given  by 

/  =  2Qsin(#?)  (22) 


where  Cl  is  the  angular  frequency  of  the  Earth's  rotation  and  (p  is  latitude. 

The  depth-mean  horizontal  eddy  viscosity  coefficient,  D,  is  dependent  on  the 
strength  of  mixing  in  the  water  column  which  is  a  function  of  the  acting 
processes  at  a  location.  If  waves  do  not  contribute  significantly  to  mixing,  D  can 
be  calculated  as  a  function  of  the  total  water  depth,  current  speed,  and  bottom 
roughness  as  (Falconer  1980) 


1.15«g(A+ti)|J 


(23) 


where  the  subscript  o  denotes  oceanic  mixing.  The  form  of  the  eddy  viscosity 
coefficient  given  by  Equation  23  results  in  mixing  terms  that  are  weakly 
nonlinear. 

In  the  surf  zone,  waves  contribute  significantly  to  lateral  mixing,  and  the 
eddy  viscosity  coefficient  is  expected  to  be  a  function  of  the  wave  properties. 
Here,  surf  zone  mixing  is  given  by 

Dw  =  eL  (24) 


where  eL  describes  the  lateral  mixing  below  trough  level  (Smith  et  al.  1993)  and 
is  expressed  as  (Kraus  and  Larson  1991) 

sL=AumH  (25) 
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where  A  is  an  empirical  coefficient  representing  the  lateral  mixing  strength,  and 
u,„  is  the  amplitude  of  the  horizontal  component  of  the  wave  orbital  velocity  at 
the  bottom  given  by 


W„  =  -p 


gHT 


2X  cosh 


2n(h  +  r\) 
_ 


(26) 


where  T  is  the  wave  period. 

Mixing  is  a  vigorous  three-dimensional  (3-D)  process  in  the  surf  zone  and 
cannot  be  represented  directly  in  a  depth-averaged  model.  Such  vertical 
processes  cannot  be  directly  described  in  a  depth-average  model;  the  mixing 
coefficient  in  Equation  25  should  be  considered  as  a  surrogate.  Streaming  from 
undertow  advects  turbulent  eddies  or  mixing  offshore,  and  this  mixing  can 
support  a  strong  current  seaward  of  the  wave  breakpoint  (Putrevu  and  Svendsen 
1992).  With  further  distance  seaward,  the  vertical  current  decreases  as  the 
volume  of  water  increases,  weakening  the  mixing  and  the  longshore  current. 

The  transition  between  surf  zone  mixing  and  oceanic  mixing  seaward  of  the 
breakpoint  is  represented  in  M2D  by  a  weighted  mixing  coefficient  specified  as 

D  =  {\-%)D0+%DW  (27) 


where  the  weighting  parameter  0  is 


0  = 


f 


H 


V 


(28) 


The  method  of  weighting  and  the  weighting  parameter  are  ad  hoc  and  must  be 
validated  by  comparison  to  data.  Intuitively,  a  cubic  dependence  on  water  depth 
introduces  the  fluid  volume. 


To  illustrate  the  control  on  the  cross-shore  distribution  of  the  longshore 
current  by  wave  friction  and  representation  of  mixing,  four  simulations 
corresponding  to  Visser  (1982)  Case  4  were  conducted.  Details  of  the  Visser 
laboratory  data  and  M2D  grid  and  parameter  values  are  given  in  Appendix  H 
with  one  difference  being  that  the  Manning’s  n  value  for  velocities  discussed  in 
this  section  was  0.013.  The  four  simulations  consisted  of  combinations  of  wave 
friction  specification  and  mixing  coefficient.  Simulations  denoted  as  “No  Wave 
Friction”  did  not  include  waves  as  a  source  of  friction,  whereas  “Wave  Friction” 
denoted  the  bottom  stress  as  defined  by  Equations  11  and  12.  Mixing 
coefficients  were  calculated  as  “Wave  Mixing,”  which  indicated  application  of 
Equation  24,  and  “Weighted  Mixing,”  which  denoted  the  combined  oceanic  and 
surf  zone  mixing  described  by  Equation  27. 
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Calculated  and  measured  longshore  current  for  Visser’s  Case  4  are  compared 
in  Figure  1 .  Values  of  distance  increase  toward  the  offshore  direction.  Peak 
calculated  current  speed  varies  between  0.37  and  0.40  m/s  and  the  measured  peak 
speed  is  0.39  m/s.  Thus,  combinations  of  both  wave  friction  to  the  bottom  stress 
and  representation  of  the  mixing  coefficient  exert  control  on  the  maximum 
current  speed.  The  area  of  greatest  variation  among  the  calculated  speeds  is 
located  between  the  peak  current  and  the  weakening  of  the  current  with  distance 
offshore.  Calculation  with  the  weighted  mixing  coefficient  and  wave  friction 
produced  a  curve  in  which  the  magnitude  and  slope  compare  well  with 
measurements.  All  of  the  remaining  calculations  show  deviation  in  magnitude 
and  curvature  from  the  measured  values  in  the  offshore  tail. 
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Figure  1 .  Comparison  of  longshore  current  speed  values  for  Visser  Case  4 

Accurate  estimation  of  the  wind-stress  coefficient  is  necessary  for  calculating 
wind-induced  flow  in  shallow  water  ( «<  5  m).  A  short  review  describing  the 
development  of  the  variable  wind-stress  coefficient  implemented  in  M2D  is 
presented  here. 

The  flux  of  momentum  into  the  water  column  from  the  wind  is  specified  as  a 
function  of  the  wind  speed  and  wind-stress  coefficient.  Anemometer  height 
above  the  water  or  land  surface  must  be  considered  for  accurate  estimation  of  the 
wind-stress  coefficient  because  wind  speed  varies  logarithmically  in  the  vertical 
direction  for  unstratified  atmospheric  conditions.  A  general  law  for  the  vertical 
wind  profile  is  given  by  (Chamock  1955;  Hsu  1988) 

W  7 

W  =  — In—  (29) 

K  Z0 
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where 


Wz  =  wind  speed  at  height  Z  above  the  surface 
Z0  =  surface  roughness 
W.  -  friction  velocity 
k  =  von  Karman  constant 

The  friction  velocity  is  defined  in  terms  of  the  surface  wind  stress  r0  as  (Hsu 
1988) 


r2  ^  dW 

%=PaW>  =  PaKm^ 


(30) 


where  Km  is  an  eddy  viscosity  coefficient  and  z  is  the  vertical  dimension. 

Under  the  assumption  of  nearly  neutral  atmospheric  stability,  the  wind-stress 
coefficient  over  water  at  a  height  10  m  above  the  water  surface,  Ci0,  can  be 
expressed  as  (Hsu  1988) 


*  v 

J4.56-21nJF10> 


(31) 


where  Wl0  is  the  wind  speed  in  m/s  at  10  m  above  the  surface.  Development  of 
Equation  31  includes  the  assumption  of  fully  developed  seas.  For  measurements 
of  wind  speed  made  at  heights  other  than  10  m,  an  approximation  for  the  10-m 
wind  speed  is  {Shore  Protection  Manual  1984) 


*io  =  *. 


'10^ 

UJ 


1/7 


(32) 


The  surface  wind-stress  Equations  15  and  16,  as  implemented  in  M2D,  apply  the 
10-m  wind-drag  coefficient  and  wind  speed  to  compute  the  surface  stress.  Thus, 
values  of  Cio  and  W\ ()  defined  by  Equations  31  and  32  are  specified  as  Cj  and  W 
in  Equations  15  and  16. 

Equations  3  land  32  have  been  successfully  applied  in  modeling  studies 
investigating  motion  in  strong  wind-forced  shallow  embayments  with  typical 
depths  ranging  from  1  to  4  m  (Brown  et  al.  1995a;  Kraus  and  Militello  1999; 
Militello  2000).  Calculated  water  level  and  current  compared  well  with 
measurements,  indicating  that  these  formulations  are  satisfactory  for  estimation 
of  the  vertical  wind  profile  and  wind  stress  in  shallow-water  systems. 
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3  Numerical  Implementation 
of  Governing  Equations 


Grid  definition  and  discretization  of  the  governing  equations  are  described  in 
this  chapter.  The  governing  equations  are  solved  numerically  on  a  staggered 
rectilinear  grid  by  a  finite-volume  calculation  approach.  All  spatial  derivatives 
are  approximated  with  central  differences  with  the  exception  of  the  advection 
terms,  for  which  an  upwind  algorithm  is  applied.  The  solution  method 
implemented  is  a  flux-based  approach  in  which  M2D  solves  the  momentum 
equations  first,  followed  by  the  continuity  equation  wherein  updated  velocity 
values  are  applied. 

To  maximize  efficiency  of  memory  for  domains  with  complex  shorelines,  the 
M2D  grid  is  stored  in  a  1 -dimensional  (1-D)  array  rather  than  a  2-D  matrix.  The 
cell  numbering  convention  is  described  in  this  chapter.  Information  is  also 
provided  on  the  Courant  stability  criterion,  which  provides  the  user  with  an  initial 
approximation  of  an  appropriate  model  time-step. 


Rectilinear  Grid 

The  governing  equations  are  solved  on  a  discretized  domain  where  cells  are 
defined  on  a  rectilinear  grid  (which  can  be  regular  or  irregular)  as  shown  in 
Figure  2.  Each  cell  has  indices  /  and  j  that  correspond  to  its  position  along  the  x- 
and  y-axes  of  the  grid  domain,  respectively.  Water-surface  elevation  is 
calculated  at  the  cell  center,  whereas  the  x-  and  y-components  of  the  velocity  are 
calculated  on  the  left  face  center  and  bottom  face  center  of  the  cell,  respectively. 
Values  of  flow  rate  per  unit  width,  qx  and  qy,  are  calculated  at  the  same  locations 
as  u  and  v,  respectively.  Because  the  best  orientation  of  the  grid  may  be  such  that 
the  x-  and  y-axes  do  not  correspond  to  geographical  coordinates  (N-S  and  E-W), 
cells  in  the  grid  are  defined  in  a  local  (or  grid)  coordinate  system.  The  local 
coordinate  system  is  referenced  to  geographic  coordinates  by  specification  of  the 
angle  between  the  y-axis  and  true  north.  A  positive  value  of  this  angle  denotes 
clockwise  rotation  and  the  maximum  rotation  angle  should  not  exceed  45  deg  to 
retain  an  orientation  as  close  to  geographic  as  possible. 
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Figure  2.  Cell  and  variable  definitions  for  M2D 


The  2-D  array  format  for  referencing  cell  locations  is  retained  here  to 
facilitate  the  presentation  of  the  finite-volume  approximations.  Mapping  of  the 
cell  indices  from  a  2-D  array  to  a  1-D  array  is  conducted  primarily  to  reduce 
computer  memory  requirements.  Details  of  the  1-D  indexing  of  cells  are 
discussed  later  in  this  section. 


Momentum  Equations 

The  finite-difference  scheme  for  the  x -momentum  equation  will  be  given 
first,  followed  by  that  for  the  y-momentum  equation.  Calculation  of  the  bottom 
stress  coefficient,  wind  stress,  eddy  viscosity  coefficient,  and  adjustment  to  the 
wave  stress  for  shallow  water  follow  the  finite-difference  approximation  of  the  y- 
momentum  equation  because  their  descriptions  are  common  for  both  x-  and  y- 
momentum  equations. 

Solution  of  the  momentum  equations  is  conducted  to  calculate  the  x-  and  y- 
components  of  velocity  u  and  v,  respectively.  The  explicit  approach 
implemented  in  M2D  solves  each  momentum  equation  for  the  corresponding 

flow  rate  per  unit  width  qk+ '  or  qk+]  at  the  present  time-step  k+l  from  values 
calculated  at  time-step  k.  Velocity  components  ukj  and  are  then  calculated 
from  the  values  of  qk+]  and  qk+i ,  respectively. 

Xi,j  SiJ 
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x-momentum  equation 


The  x-momentum  equation  is  solved  explicitly  by  a  finite-volume 
approximation  for  the  control  volume  shown  in  Figure  3.  The  control  volume  is 
indicated  by  the  dashed  blue  line.  Surface  and  bottom  stresses  (i.e.,  wind  and 
friction)  are  approximated  on  the  upper  and  lower  surfaces  and  momentum  fluxes 
are  approximated  at  each  cell  face. 


Figure  3.  Control  volume  definition  for  x-momentum  equation 
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where 


i,j  =  cell  location  on  the  grid 
k  =  time-step 

Av(-  j  =  cell-side  length  parallel  to  the  x-axis 
A ytj  =  cell-side  length  parallel  to  the  y-axis 


and 


^xMn J  ~UM/2 .fix’  Ui+V2,j 


qk  -qk 

pk  _  -k  ■  -k  ^-1.7 

**  ~Ui-M2,jQx’  Ui-U2,j 


2(hi-l,j+r\i  u) 


if  "*.,/>  0 


<h  =  L 


if  uk_UJ  <  0 


c+>  - 


(^j+Tiij+^j+i+%») 


+- 


2^/-i,y+i 


( Vij  +  Tl,-ij + Vij+i  +  riI  -1,7+1  ) 


^  ^>0 


(34) 


(35) 


(36) 
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gKj^- 


Jy>.j 


(\y'+rl,j+4j-l+'n,j-l) 


(Vu+TlM,y  +  Vij-i+Tl,-,j-i) 

*;=< 


The  x-directed  current  velocity  is  given  by 

k 


u, . 


(37) 


u  +nf.u) 

and  the  current  speed  for  the  x-momentum  equation  is 

k  \2  /  *\2  *  (v*y+V*,  J+V*.+,  +vf_1J+1) 

I = VK/ ) +  (v* )  where  v* =  — — ^ - - 


(38) 


(39) 


Wave  stress  for  the  x-momentum  equation  tSx  is  given  by 


(  \m  1 
r  w 


(ds„  Y+1  fas, 


v  &  juj 


+ 


\*+l 


^  A/ 


(40) 


y-momentum  equation 

The  y-momentum  equation  is  solved  explicitly  with  a  finite  volume 
approximation  for  a  control  volume  as  shown  in  Figure  4.  The  control  volume  is 
indicated  by  the  dashed  blue  line.  Surface  and  bottom  stresses  (i.e.,  wind  and 
friction)  are  approximated  on  the  upper  and  lower  surfaces  and  momentum  fluxes 
are  approximated  at  each  cell  face. 
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Figure  4.  Control  volume  definition  for  y-momentum  equation 


The  y-momentum  equation  is  finite  volume  form  is  given  by 


+ fo*  ~  Fly,  K + 

(Au  +i«)2  -(\h  +n«-i)2]^,/  = 


At 

1 


Aru  Av,j-i 

+{(<  +1C  +<„  +<^)Ax-.A’u 

-(c*)‘j  vu|ruKuA>'u+<.JA)c<.Au 

/  \*+l 


4*., 


where  Aqy,  ,  =  ?**'  -qky>j  and 


(41) 
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The  y-directed  current  velocity  is  given  by 


v, ,  =  2 


( hi + Tif,y + Kj- i +  nL-. ) 


(42) 
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and  the  current  speed  for  the  y-momentum  equation  is 


\rrk\  1/  k\2  7  1  \2  ,  k  {UU+UMJ+UU-i+UMJ-l) 

rirvl"*)  +0w  where  = - i - 


(47) 


Wave  stress  for  the  y-momentum  equation  xs>,  is  given  by 

f  ^  l\(dS„AM  ( 8S.  ^+' 

(T*i 


V  8x  J 


ty  Jij 


(48) 


Bottom-friction  coefficient 

The  bottom-friction  coefficient  (Cb  .  is  given  by 


(49) 


where  Cjj  is  the  Chezy  coefficient  calculated  as 


(50) 


where  7?  .  is  the  hydraulic  radius,  which  is  dependent  on  the  cell  dimension  As , 

in  the  corresponding  flow  direction.  The  hydraulic  radius  for  a  given  cell  is 
calculated  by 


<J  = 


Ps 


(51) 


where  is  the  wetted  perimeter  of  the  cell,  and  As  denotes  Ax  or  Ay  for 
application  of  Equation  51  to  the  x-  ory-momentum  equation,  respectively.  The 
wetted  perimeter  is  taken  to  be  equal  to  As  if  a  cell  has  no  impermeable  walls. 
If  walls  are  present,  the  wetted  perimeter  is  calculated  by 


As,. ,  +  m\ 


(52) 


where  m  is  the  number  of  wall  boundaries  on  sides  parallel  to  the  component  of 
flow  corresponding  to  s.  For  example,  in  the  case  of  flow  along  a  one-cell-wide 
channel  aligned  with  the  x-axis,  the  wetted  perimeter  would  be  calculated  as 
P  -  Ax  +  2 (h  +  rj)  at  all  cells  in  the  channel.  If  the  channel  is  two  cells  wide, 
then  the  wetted  perimeter  for  the  jc-momentum  equation  would  be  calculated  as 
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P  =  Ax  +  (h  +  r|) .  The  formulation  of  the  bottom-friction  coefficient  takes  into 

account  wall  friction,  but  does  not  distinguish  it  from  friction  along  the  channel 
bottom.  In  addition,  calculation  of  the  wetted  perimeter  does  not  account  for 
changes  in  depth  between  adjacent  cells  (increase  in  wetted  surface  area). 

Inclusion  of  waves  in  the  bottom  stress  is  implemented  by  representing  the 
combined  wave  and  current  terms  of  Equations  1 1  and  12,  respectively,  as 
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where 
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Because  the  wave  properties  are  scalar  values,  they  are  located  at  cell  centers  and 
must  be  face-averaged  for  application  in  the  bottom  stress  calculation. 


If  water  in  a  cell  approaches  a  thin  layer,  numerical  instability  may  arise  and 
unrealistically  large  values  of  water  level  and  current  speed  can  be  calculated. 
This  numerical  problem  is  more  apparent  than  real  because  water  creeping  onto  a 
dry  surface  is  expected  to  experience  large  frictional  resistance.  Stability  in 
shallow  water  is  enhanced  within  M2D  by  adjustment  of  the  bottom-friction 
coefficient  by  the  following  formulation 


adjusted 


,,=(c£ 


1  +  exp 


a[h,j+nlj 


(67) 


where  the  subscript  adjusted  denotes  the  modified  bottom-friction  coefficient, 
and  a  is  a  parameter  that  controls  the  gradient  of  the  increase  of  the  bottom- 
friction  coefficient  as  the  water  depth  approaches  zero.  The  bottom-friction 
coefficient  can  vary  within  the  range  Cb  to  2  Cb  with  the  adjustment  scaled  by 
the  exponential  expression  given  within  Equation  67.  Figure  5  shows  the  depth- 
dependent  adjustment  of  the  bottom-friction  coefficient  as  given  by  the 
exponential  formulation  with  the  parameter  a  set  to  10.  Significant  increases  in 
the  bottom-friction  coefficient  occur  for  small  water  depth,  particularly  less  than 
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0.1  m  because  of  the  presence  of  large  roughness  elements  relative  to  the  water 
depth.  Thus,  modification  of  the  bottom-friction  coefficient  from  its  normal 
value  is  restricted  to  small  water  depth.  For  depths  greater  than  approximately 
0.2  m,  modification  of  the  bottom-friction  coefficient  is  small. 


Depth,  m 


Figure  5.  Bottom-friction  coefficient  adjustment  versus  total  water  depth 


Wind  stress 

Wind-stress  terms  are  calculated  by 

t„=C.A  (<')Jcos(e“)  (68) 

P  W 

V=cA('C)!sm(e“)  (69) 

P  vi 

where  Q  is  calculated  by  Equation  3 1  and  Wi0  has  been  calculated  from  W. 
Height  of  the  anemometer  is  specified  in  an  input  file.  Wind  forcing  in  M2D  can 
vary  over  time,  but  is  homogenous  over  space. 
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Eddy  viscosity  coefficient 


Two  formulations  for  calculation  of  the  eddy  viscosity  coefficient  are 
implemented  in  M2D,  one  for  oceanic  mixing  and  one  for  surf  zone  mixing.  If 
waves  are  not  present,  the  oceanic  coefficient  of  eddy  viscosity  is  calculated  as 


These  formulations  are  calculated  for  Manning’s  n  >  0.  For  ffictionless  cells, 
specified  by  n  =  0 ,  D0  =  0.0  m2/s. 

In  the  presence  of  waves  and  wave  breaking,  the  eddy  viscosity  coefficient  is 
calculated  as 
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Wavelength  X,  is  calculated  by  the  Eckart  approximation 
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where  X0  is  the  deepwater  wavelength  given  by 


K 


ill ‘1 

2n 


(82) 


and  co  is  the  wave  frequency  given  by 


co*  = 


271 


(83) 


Wave  parameters  are  calculated  at  locations  corresponding  to  indices  on  Dw, 

If  waves  are  present  but  not  breaking,  then  the  mixing  coefficient  is 
calculated  as  a  weighted  function  of  the  oceanic  and  wave  mixing  values  as 

Dk  =  (l-0*)(Z)o)*+e*  (Dw)k  (84) 
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where  the  weighting  parameter  0  is 


0*  = 


'  Hk  V 

Kh+r\k  j 


(85) 


Equations  84  and  85  are  calculated  and  applied  at  locations  corresponding  to 
indices  on  D0  and  Dw. 

Wave  stress  scaling  for  shallow  water 

M2D  accepts  wave  stresses  calculated  by  a  wave  model  and  those  stresses 
can  vary  spatially  over  the  computational  domain.  Wave  stresses  must  be 
mapped  from  the  wave  model  onto  the  M2D  domain.  In  water  depths  of  0.35  m 
or  less,  the  wave  stresses  are  reduced  by 


T*=T*  035  ’  for  (*u+<y)s  0.35m  (86) 

where  x^  is  the  adjusted  wave  stress  and  is  applied  to  both  xSx  and  xSy  if  the 

depth  criterion  is  met.  Equation  86  scales  the  wave  stress  toward  zero  as  the 
water  depth  decreases. 

Wave  models  typically  perform  calculations  in  a  local  right-handed 
coordinate  system  in  which  positive  x  is  directed  onshore  and  positive  y  is 
directed  alongshore.  Thus,  the  orientation  of  the  local  coordinate  system  may  not 
be  aligned  with  global  geographic  coordinates.  M2D  performs  calculations  on  a 
local  coordinate  system  that  is  referenced  to  global  geographic  coordinates  by  the 
deviation  of  the  y-axis  (given  in  degrees)  from  true  north.  If  wave  stresses  are 
included  in  M2D  calculations,  mapping  of  those  stresses  from  the  wave  model  to 
the  circulation  model  must  take  into  consideration  the  different  coordinate 
systems  and  grid  orientations.  Wave  stresses  calculated  by  STWAVE  can  be 
automatically  mapped  to  M2D  within  the  SMS  (see  Chapter  6). 


Continuity  Equation 

The  continuity  equation  is  solved  explicitly  for  water-surface  elevation  r]  by 
a  finite-volume  approximation  for  a  control  volume  depicted  in  Figure  6.  Mass 
fluxes  are  approximated  at  each  cell  face.  In  the  staggered  time  differencing 
scheme,  the  most  recently  calculated  values  for  the  u  and  v  velocity  components 
are  entered  into  the  spatial  derivatives.  The  finite-volume  approximation  of 
Equation  1  is  given  by 
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A\j 


A/  -vJtiZ)Ay>-J+(qyl'j  ~qy\u+ i)Axw  =  0 . (87) 

where  At],,  j  =  -  r\:j  and  all  other  variables  have  been  previously  defined. 
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Figure  6.  Control  volume  definition  for  continuity  equation 


Cell  Numbering 

M2D  stores  its  numerical  grid  in  an  array  rather  than  a  matrix,  which  saves 
memory  for  large  or  irregular  grid  domains.  The  numbering  scheme  for  the 
computational  grid  is  designed  to  be  efficient  such  that  regions  that  never  become 
computationally  active  do  not  have  to  be  stored.  For  model  domains  that  have 
complex  shorelines,  this  feature  can  save  substantial  computer  memory.  On  the 
other  hand,  for  simple  grids,  more  memory  may  be  required  because  pointing 
arrays  are  necessary  for  cell  indexing. 

The  cell  numbering  system  internal  to  M2D  does  not  require  row  and  column 
indexing,  but  instead  assigns  each  cell  a  unique  identification  number.  Flather 
and  Fleaps  (1975)  implemented  a  similar  cell  numbering  system  so  that  only  cells 
included  in  hydrodynamic  calculations  were  stored.  Non-computational  regions 
of  the  grid,  such  as  the  mainland  and  islands,  do  not  require  assigned  cell 
numbers,  so  they  do  not  occupy  space  in  memory.  Figure  7  illustrates  the  cell 
numbering  system  for  a  small  domain  that  includes  a  non-computational  region 
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indicated  by  hatching.  Cell  identification  numbers  of  neighbors  adjacent  to  a 
particular  cell  are  stored  in  a  pointing  matrix  within  the  model.  For  example, 
cell  9  has  neighbors  with  cell  identification  numbers  12,  10,  4,  and  8  moving 
from  top,  to  right,  bottom,  and  left,  respectively.  This  clockwise  order  of 
referencing  neighbor  cells  is  taken  as  convention  for  descriptions  in  this 
document. 

Locations  where  no  cells  exist,  such  as  beyond  the  computational  domain  or 
in  non-computational  regions,  such  as  islands  within  the  domain,  are  designated 
with  a  cell  number  of  0.  For  example,  cell  1 1  in  Figure  7  lies  on  the  boundary  of 
the  grid  domain  and  also  resides  next  to  a  non-computational  area.  Neighbor-cell 
specifications  for  cell  1 1  would  be  stored  as  14,  0,  6,  and  0.  The  grid  does  not 
contain  any  cells  with  cell  number  of  zero;  this  value  is  used  in  neighbor 
specification  to  indicate  that  a  computational  cell  does  not  exist  at  a  particular 
location.  If  a  cell  is  removed  from  computations,  it  retains  its  original  cell 
number,  calculations  treat  the  interfaces  of  the  neighbors  and  the  inactive  cell  as 
walls. 
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Figure  7.  Cell  numbering  system 

Removal  of  a  cell  from  computations  can  be  achieved  by  setting  its  type  to 
inactive  and  changing  its  value  to  zero  at  locations  where  it  is  referenced  as  a 
neighbor.  The  inactive  cell  would  remain  in  the  grid  and  retain  its  original  cell 
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number,  but  M2D  will  recognize  it  as  a  void  surrounded  by  walls.  As  an 
example,  if  cell  3  were  to  be  changed  to  an  inactive  type  cell,  the  neighbor 
specifications  for  cell  4  would  be  changed  from  9,  5,  0,  3  to  9,  5,  0,  0. 
Specifications  for  cell  3  would  remain  the  same,  except  that  the  type  would  be 
changed  to  inactive  (type  0). 


Courant  Condition 


For  an  explicit  solution  method,  an  initial  estimate  of  the  maximum  time-step 
for  a  grid  is  calculated  from  the  Courant  number  given  by  (Richtmyer  and 
Morton  1967) 

\  =  u~~~  (88) 

As 


The  theoretical  maximum  value  of  the  Courant  number  is  unity  for  stability  of  a 
linear,  finite-difference  hydrodynamic  model,  where  for  shallow-water  equations 

u  =  yfgh  refers  to  long  waves,  such  as  the  tide. 


Because  M2D  solves  the  nonlinear  shallow-water  equations,  stability  will  be 
maintained  for  a  Courant  number  less  than  unity.  Also,  for  a  general  situation, 
multiple  forcing  is  possible  from  a  superposition  of  sources  other  than  or  in 
addition  to  the  tide.  Contributions  to  the  current  can  be  produced  by  wind, 
surface  waves,  and  tributary  discharges.  Assigning  a  velocity  component  to  each 
of  these  forcings,  denoted  with  a  subscript,  the  Courant  number  is  more 
accurately  defined  as 


+  u 


wind 


+  U 


waves 


tributary 


(89) 


In  strong  or  focused-flow  regions  of  a  model  domain,  such  as  at  ebb  shoals 
and  in  the  surf  zone,  the  wave-driven  current  can  be  significantly  stronger  than 
the  tidal  current.  Moreover,  these  are  typically  areas  of  greater  spatial  grid 
resolution.  The  combination  of  strong  currents  and  small  grid  cells  limit  the 
allowable  size  of  the  time-step. 
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4  Boundary  Conditions 


Six  types  of  boundary  conditions  are  implemented  in  M2D,  and  these  can  be 
distinguished  as  specifying  forcing  and  non-forcing  boundaries.  Table  1  lists  the 
boundary-condition  types  and  contains  a  short  description  of  each.  Each 
boundary-condition  type  is  described  next. 


Table  1 

Boundary  Condition  Types 

|  Boundary  Condition 

Description  | 

Tidal-constituent  water  level  forcing 

'  y 

Water  level  specified  as  sum  of  tidal  constituents 

Time  series  water  level  forcing 

Water  level  specified  from  time  series  input  file 

Time  series  water  level  and  velocity 
forcing 

Water  level  and  velocities  specified  from  time  series  input 
files 

Time  series  flow  rate  forcing 

Flow  rate  specified  from  a  time  series  input  file 

Closed,  reflective  (non-forcing) 

Impermeable  boundary,  velocity  must  flow  parallel  to 
boundary 

Wave-adjusted  water  level  and 
velocity  forcing 

Boundary  water  level  and  velocity  values  are  adjusted  for 
presence  of  radiation-stress  gradients.  Provides 
compatibility  of  boundary  forcing  with  wave  forcing 

Water  Level  Forcing  Boundary  Conditions 

Water  level  forcing  can  be  specified  through  either  tidal  constituents  or  by 
time  series  water  level  read  in  from  a  file.  These  two  boundary  conditions  apply 
the  same  finite-difference  approach,  with  the  difference  between  them  being  the 
source  of  the  water  level  prescribed  at  the  boundary. 

If  a  cell  is  designated  as  a  water  surface  elevation  boundary  cell,  the 
continuity  equation  for  that  cell  is  not  solved,  and  the  water  level  is  updated  each 
time-step  according  to: 

<'=<J  <9°) 

where  rj*y.  is  a  prescribed  value.  If  tidal  forcing  is  specified,  then 
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Tidal-constituent  forcing 

Tidal-constituent  forcing  in  M2D  can  accommodate  up  to  eight  components 
of  the  astronomical  tide.  The  user  can  select  from  the  following  constituents: 

M2,  S2;  N2,  K2,  Ki,  Oi,  M4,  and  M6.  Although  the  M4  and  M6  constituents  are 
harmonics,  they  can  be  generated  in  continental  shelf  areas  and  may  be  present  as 
components  of  the  tidal  forcing  at  the  grid  boundary.  Specification  of  tidal 
constituents  requires  input  information  for  the  local  amplitude  and  phase  values. 
Tidal  forcing  by  M2D  is  simple  and  does  not  include  advanced  tidal  calculations 
or  relations  to  Greenwich  tidal  parameters  (Schureman  1924). 

Tidal  elevation  r\ljde  is  given  by 


8  (  2n  ^ 

M  VdoU  J 


(92) 


where  A  is  the  amplitude  (m),  s  is  the  speed  (deg/hr),  and  <j)  is  the  phase  (deg)  of 
the  tidal  constituent.  Constituents  can  be  eliminated  from  the  tidal  forcing  by 
setting  their  amplitudes  to  zero.  If  the  tidal  elevation  boundary  condition  is 
invoked,  water  levels  at  tidal  boundary  cells  are  computed  at  every  time-step. 
Tidal  phase  and  amplitude  is  held  constant  across  the  tidal-constituent  boundary. 
For  applications  requiring  amplitude  and  phase  variation  over  an  open  boundary, 
solutions  from  regional  models  can  be  applied  to  map  water  surface  elevations  as 
boundary  conditions  for  M2D. 


Time  series  water  level  forcing 

The  time  series  water  level  forcing  boundary  condition  is  specified  by  water 
levels  ( r| b.  j )  read  into  the  model  from  an  input  file.  Time  increments  of  the 

forcing  data  are  not  required  to  be  equal  to,  or  in  multiple  increments  of,  the 
model  time-step.  Because  the  model  will  usually  have  smaller  time-steps  than 
the  water  level  forcing  data  input,  M2D  must  be  instructed  on  treatment  of  the 
water  level  boundary  value  between  times  that  its  value  is  specified  in  the  input 
file.  One  option  is  to  keep  the  water  level  constant  between  input  water  level 
values.  A  second  option  is  to  linearly  interpolate  in  time  between  input  water 
level  values.  The  boundary  condition  input  file  for  water  level  contains  a 
parameter  that  sets  the  interpolation  option. 
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Time  Series  Water  Level  and  Velocity  Forcing 
Boundary  Condition 

The  time  series  water  level  and  velocity  forcing  boundary  condition  applies 
velocities  at  cell  boundaries  in  addition  to  water  levels.  Application  of  water 
levels  for  this  boundary  type  is  identical  to  that  previously  described  for  water 
level  forcing  boundary  conditions.  Velocities  prescribed  on  the  boundaries  enter 
the  momentum  equation  through  the  advective  terms.  Discretization  of  the 
momentum  equations  for  applying  velocities  on  the  boundaries  is  identical  to  the 
implementation  for  nonboundary  cells  described  in  Chapter  3. 


Time  Series  Flow  Rate  Forcing  Boundary 
Condition 


The  time  series  flow  rate  forcing  boundary  condition  can  be  assigned  at 
locations  where  the  flow  rate  is  known.  Typical  examples  where  this  boundary 
condition  is  applied  are  natural  tributaries  (rivers,  streams,  and  creeks), 
controlled-discharge  canals,  and  anthropogenic  intake  or  discharge  locations  such 
as  for  power  plant  cooling  water  or  treatment  plant  outfalls. 

A  flow  rate  boundary  condition  specifies  discharge  at  one  or  more  cells  on 
the  grid  boundary.  If  a  cell  is  designated  as  a  flow  rate  boundary  cell,  the 
momentum  equation  for  the  appropriate  cell  face  is  not  solved,  and  the  flow- 
component  normal  to  the  face  is  prescribed.  Because  M2D  operates  on  a 
staggered  grid,  “imaginary”  cells  are  added  to  the  right  or  top  of  the  grid  at  flow 
rate  forcing  boundary  cells  prescribed  on  those  sides.  This  addition  of  imaginary 
cells  is  required  to  provide  access  to  cell  faces  on  the  right  or  top  of  the  grid. 

For  a  flow  rate  forcing  cell  located  on  the  right  side  of  the  grid  at  location 
/+ 1  j/,  the  flux  is  given  by 


Qb 

A Ymj 


(93) 


where  Qx  i  is  the  input  flow  rate  directed  parallel  to  the  x-axis  and  i  + 1 
denotes  an  imaginary  cell  adjacent  and  to  the  right  of  the  ih  cell. 

For  a  flow  rate  forcing  cell  located  on  the  left  side  of  the  grid  at  location 
i-lj\  the  flux  is  given  by 


Q. 


*1-1,7 


a yt,j 


(94) 
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For  a  flow  rate  forcing  cell  located  on  the  top  side  of  the  grid  at  location 
ij+l,  the  flux  is  given  by 


Ax.. 


i,j+l 


(95) 


where  Qby  is  the  input  flow  rate  directed  parallel  to  the  y-axis. 

For  a  flow  rate  forcing  cell  located  on  the  bottom  side  of  the  grid  at  location 
ij- 1 ,  the  flux  is  given  by 


Ax,. 


(96) 


Closed,  Reflective  Boundary  Condition 

The  closed,  reflective  boundary  condition  is  specified  at  impermeable 
boundaries,  such  as  the  land-water  interface.  These  boundaries  behave  as  walls; 
water  can  flow  parallel  to  the  wall  face,  but  not  through  it.  The  boundary 
conditions  are  similar  to  flow  rate  boundary  conditions  except  that  zero  flow  is 
prescribed. 

The  normal  velocity  at  the  closed  boundary  on  the  left  cell  face  is 

0*+,=  0  (97) 

*i,j 

and  the  normal  velocity  at  the  closed  boundary  on  the  bottom  face  is 

Qk*  =  0  (98) 

Closed  boundaries  on  the  right  and  top  cell  faces  are  prescribed  at  the  imaginary 
cells  i+lj  and  ij+l,  respectively. 


Wave-Adjusted  Water  Level  and  Velocity  Forcing 

Simulations  for  nearshore  areas  may  have  available  boundary  forcing 
information  that  does  not  include  the  presence  of  waves.  The  wave-adjusted 
water  level  and  velocity  boundary  condition  modifies  the  prescribed  forcing 
values  to  account  for  waves.  If  water  level  forcing  or  mixed  water  level  and 
velocity  forcing  are  applied  together  with  radiation-stress  forcing,  then  in  this 
boundary  condition,  boundary  values  are  adjusted  for  wave-driven  current  and 
setup  or  setdown.  The  boundary  adjustment  is  conducted  by  creating  a  surface 
deflection  (setup  and  setdown)  consistent  with  that  of  the  interior  solution  so  that 
radiation  stress-forced  flow  can  move  smoothly  through  the  boundary.  It  is 
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believed  that  this  boundary  condition  is  new  to  coastal  circulation  modeling  and 
will  be  reported  in  more  detail  elsewhere  (Reed  and  Militello,  in  preparation). 


Adjustment  to  the  prescribed  boundary  conditions  is  conducted  by  solving 
the  1-D  continuity  and  momentum  equations  normal  to  the  boundary,  in  which 
the  radiation  stress  gradient  is  included  in  the  momentum  equation.  The  forms  of 
the  1  -D  continuity  and  momentum  equations  for  the  x-direction  are 


g(jHJ3fc+2fl  t  dg;  _0 

dt  ox 


(99) 


eg  ,  3u’q:  1 1  m+ru+rQ 

dt  dx  2  dx 


^bx+Kx+XSx 


(100) 


in  which 

r|  =  r|6+rl'  (101) 

where  r|  is  the  applied  boundary  condition,  r|6  is  the  prescribed  boundary  value 
(read  from  a  file),  and  r|' and  u'  are  the  solutions  from  Equations  99  and  100,  and 
Qx  is  given  by 


Q'x=u’(h(x)  +  r|'(x))  (102) 

where  h  (x)  and  rj  (jc)  are  denote  face-centered  averages  that  place  h  and  r|  at 

the  same  position  as  u  .  If  the  boundary  is  specified  a  mixed  water  surface 
elevation  and  velocity  boundary,  then  the  w-component  of  velocity  assigned  at 
the  boundary  is  modified  by 

u  =  ub+u'  (103) 

where  u  is  the  applied  velocity  at  the  boundary  and  ub  is  the  prescribed  velocity 
(read  from  a  file). 

The  1-D  continuity  and  momentum  equations  for  the  y-direction  are 


d^  +  TU+Tfl  ,  gg y  =Q 

dt  dy 


(104) 


gg  ,  ^'g  ,  i 

dt  dy  2  dy 


— X.  +  X  H-Xc 

yby  wy  Sy 


(105) 
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where  r)'and  v'  are  the  solutions  from  Equations  104  and  105,  and  Qy  is  given 
by 


=v(h  (j)  +  T]'(y))  (106) 

where  h  (y)  and  rj  (y)  are  face-centered  averages  that  place  h  and  r|  at  the 

same  position  as  v  .  If  the  boundary  is  specified  as  a  mixed  water  surface 
elevation  and  velocity  boundary,  then  the  v  component  of  velocity  assigned  at  the 
boundary  is  modified  by 

v  =  v,+v'  (107) 

where  v  is  the  applied  velocity  at  the  boundary  and  v*  is  the  prescribed  velocity 
(read  from  a  file). 

The  wave-adjusted  boundary  condition  is  demonstrated  for  an  idealized 
beach  in  Appendix  G. 
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5  Model  Features 


Features  have  been  implemented  into  M2D  to  improve  the  representation  of 
calculated  hydrodynamics  and  to  provide  flexibility  to  the  user.  This  chapter 
describes  these  features  and  provides  information  on  model  options.  Topics 
covered  are:  flooding  and  drying,  hot-start  options,  model  spin-up,  coupling  with 
larger-scale  circulation  models,  coupling  with  wave  models,  and  output  options. 


Flooding  and  Drying 

Numerical  modeling  of  shallow-water  areas  with  expansive  tidal  or  wind- 
tidal  flats  is  most  accurately  performed  if  realistic  and  robust  flooding  and  drying 
algorithms  are  included  in  the  computations.  Representation  of  flooding  and 
drying  also  eliminates  the  need  to  modify  grid  depth  to  avoid  artificially  induced 
instabilities.  Numerical  simulation  of  flooding  and  drying  of  cells  or  elements  in 
hydrodynamic  models  has  been  performed  with  various  techniques  such  as 
application  of  barrier  and  weir  equations  (Reid  and  Bodine  1968;  Butler  1978; 
Wanstrath  1978)  and  moving  boundaries  (Yeh  and  Chou  1978).  A  simple  and 
robust  flooding  and  drying  algorithm  has  been  implemented  to  represent 
inundation  and  drying  of  shallow  areas  of  the  model  domain. 

Criteria  were  established  for  the  flooding  and  drying  algorithms  implemented 
in  M2D  and  are  given  in  Table  2.  The  criteria  were  specified  so  that  the 
algorithms  would  produce  realistic  behavior,  and  numerical  problems,  such  as 
oscillations  and  flutter,  would  be  minimized. 


Table  2 

Criteria  for  Flooding  and  Drying  Algorithms 

Flooding 

Comments  | 

Water  depth  must  exceed  a  predetermined  minimum 
depth  in  adjacent  cells 

Transfer  of  physically  meaningful  water 
volume,  avoids  flutter 

Water  must  be  moving  toward  dry  cell 

Takes  into  account  wind-induced  setup, 
avoids  instability 

|  Drying 

Comments 

Total  water  depth  is  less  than  predetermined  minimum 
depth 

Definition  of  drying 
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Every  wet  cell  is  checked  to  determine  whether  or  not  it  has  dried  after  new 
water  level  and  velocity  values  have  been  calculated  over  the  model  domain. 
The  criterion  for  a  cell  to  be  dry  is 


(108) 


where  Hi  ■  is  the  total  water  depth,  and  Hcr  is  a  depth  below  which  drying  is 

assumed  to  occur.  If  a  cell  or  its  adjacent  neighbor  to  the  south  or  west  has 
become  dry,  restrictions  on  flow  between  the  two  cells  are  imposed.  Restrictions 
governing  flow  across  the  two  faces  are  imposed  for  the  following  conditions: 


a.  Both  cells  on  each  side  of  a  face  are  dry 
H,j  <  Hcr  and  HiAJ  <  Hcr,  =  ukJ  =  0 

Hu  <  Hcr  and  Hi<H  <  Hcr,  vj,  =  =  0 


(109) 

(110) 


This  restriction  sets  the  velocity  at  the  face  to  zero  so  that  there  is  no 
transfer  of  water  between  dry  cells. 


b.  Neighbor  to  south  or  west  is  dry,  and  cell  i,j  is  wet 
H,J  >  and  HMJ  <  H„  and  «*,  >  0.  **,  =  »**'  =  0 

H:J  >  H„  and  H,j_,  <  H„  and  v*;  >  0,  v*y  =  v‘*‘  =  0 


(HI) 

(112) 


This  restriction  sets  the  velocity  at  the  face  to  zero  if  the  velocity  at  the 
previous  time-step  indicates  transfer  of  water  from  a  neighboring  dry  cell 
to  the  wet  cell  ij.  Water  is  allowed  to  flow  from  the  wet  cell  to  the 
neighboring  dry  cell. 


c.  Neighbor  to  south  or  west  is  wet,  and  cell  /j  is  dry 
H,  J  <  H,  and  HiAJ  >  H„  and  a,*,  <  0,  «*,  =  a*;’  =  0 

H,j  <  H„  and  H,h  >  H"  and  <  0,  v‘,  =  v*;1  =  0 


(113) 

(114) 


This  restriction  sets  the  velocity  at  the  face  to  zero  if  the  velocity  at  the 
previous  time-step  indicates  transfer  of  water  from  dry  cell  ij  a 
neighboring  wet  cell.  Water  is  allowed  to  flow  from  the  neighboring  wet 
cell  to  the  dry  cell  ij. 
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Hot-Start  Capabilities 

M2D  has  two  hot-start  capabilities  and  both  can  be  invoked  during  a 
simulation.  The  two  hot-start  types  are: 

a.  Hot-start  file  written  once  during  a  simulation  at  a  user-specified  time. 
The  file  name  prefix  is  given  by  the  user.  This  file  can  be  opened  in 
future  simulations  to  initialize  M2D  at  a  convenient  time,  such  as  after 
the  model  has  spun  up. 

b.  Hot-start  file  written  at  user-specified  intervals.  If  this  option  is  invoked, 
M2D  will  alternate  hot-start  file  names  HOTSTART1.M2I  and 
HOTSTART2.M2I  each  time  a  hot-start  file  is  written.  An  information 
file  called  HOTSTART.INFO  is  also  written  that  contains  the  name  of 
the  last  hot-start  file  that  was  written  and  the  simulation  time,  in  hours, 
when  the  hot-start  file  was  saved.  These  hot-start  files  are  helpful  in 
restarting  simulations  that  terminate  unexpectedly,  such  as  by  power 
outage. 


Model  Spin-Up:  Ramp  Function 

Model  spin-up  is  controlled  by  a  hyperbolic  tangent  function  that  scales  the 
model  forcing  over  a  user-specified  interval.  A  time-dependent  scaling  factor 

fromp  is  computed  as 


framp  =  tanh 


'  /  ' 

4.5 - 

T 

y  ramp  J 


(115) 


where  Tramp  is  the  time  over  which  the  model  is  spun  up.  All  model  forcing  is 
multiplied  by  the  scaling  factor  over  the  duration  of  the  ramp.  After  the 
simulation  time  exceeds  the  ramp  duration,  the  scaling  factor  is  set  to  1.0. 


Coupling  with  Larger-Domain  Model 

M2D  can  be  operated  as  a  detailed  inset  of  a  larger-domain  model.  This 
capability  provides  a  means  of  maintaining  hydrodynamic  properties  at  the  M2D 
boundaries,  flexibility  in  resolution  over  the  project  area,  and  application  of 
options  contained  within  M2D  that  may  not  be  available  in  other  models. 
Coupling  can  be  invoked  by  application  of  water  surface  elevations  or  the 
combination  of  water  surface  elevations  and  velocities  as  M2D  forcing 
boundaries,  where  the  values  have  been  obtained  from  a  larger-domain  model. 
SMS  provides  an  automated  procedure  for  extracting  and  mapping  boundary 
information  from  a  larger-domain  model  to  M2D  (see  Chapter  6  for  details). 
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M2D  can  accept  boundary  information  from  any  larger-domain  model, 
including  another  M2D  project.  Considerations  for  coupling  with  a  larger- 
domain  model  are  discussed  here  with  an  example  shown  for  M2D  forced  by 
water  surface  elevations  and  velocities  calculated  by  ADCIRC.  If  a  larger- 
domain  model  is  to  provide  boundary  conditions  for  M2D,  mesh  or  grid 
resolution  of  the  larger-domain  model  in  the  area  of  the  M2D  boundary  must  be 
sufficient  to  describe  details  of  the  hydrodynamic  field  at  the  scales  required  for 
the  particular  project.  Figure  8  shows  an  M2D  grid  overlaid  on  a  portion  of  an 
ADCIRC  mesh  developed  for  Shinnecock  Inlet,  NY.  Distances  between 
ADCIRC  nodes  are  a  few  times  larger  than  the  M2D  cell  sizes,  but  are  not 
greatly  larger.  If  the  ADCIRC  nodes  were  spaced  further  apart,  having  only  a 
few  nodes  in  the  vicinity  of  the  M2D  boundary,  details  of  the  flow  field  would 
not  be  adequately  described  to  capture  the  inlet  and  ocean  hydrodynamics  of  the 
area. 


Figure  8.  M2D  grid  and  ADCIRC  mesh  for  Shinnecock  Inlet,  NY 


Temporal  resolution  of  the  boundary  information  provided  to  M2D  from  the 
larger-domain  model  must  also  be  considered.  Output  frequency  of  larger- 
domain  model  solutions  should  be  set  to  minimize  error  in  forcing  for  the  scales 
of  motion  calculated.  As  an  example,  water  level  curves  calculated  by  the 

function  r\  =  sin  (2nt/ 12.42) ,  where  t  is  in  hours,  and  output  at  increments  of 

1.0  and  0.25  hr  are  shown  in  Figure  9.  Output  at  0.25  hr  produces  a  curve  that 
describes  the  water  level  significantly  better  than  the  curve  output  at  1 .0  hr.  An 
example  of  the  error  introduced  by  the  1-hr  interval  output  is  shown  at  the  second 
peak,  in  which  a  3-cm  difference  is  encountered. 
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Figure  9.  Time  discretization  of  a  sinusoidal  water  level  curve 


Coupling  with  STWAVE 

M2D  and  STWAVE  can  be  coupled  through  the  SMS  Steering  Module  (refer 
to  Chapter  6  for  details).  Coupling  can  be  conducted  by  forcing  M2D  with 
radiation-stress  gradients  calculated  by  STWAVE  and  by  applying  currents  and 
water  depth  ( h  +  r|)  calculated  by  M2D  as  input  to  STWAVE.  The  user  has  the 
option  of  selecting  one  or  more  of  these  linkages.  Guidance  is  provided  here  to 
assist  the  user  in  setting  up  a  correct  and  successful  coupled  simulation. 

M2D  and  STWAVE  calculate  on  different  coordinate  systems  that  may  or 
may  not  be  aligned,  depending  on  the  orientation  of  the  shoreline  relative  to 
geographic  coordinates.  The  coordinate  system  for  M2D  is  ±  45  deg  from 
geographic  coordinates,  meaning,  that  positive  x  is  directed  within  45  deg  of  east 
and  positive  y  is  directed  with  45  deg  of  north.  An  angle  provided  in  the  M2D 
control  file  defines  the  deviation  of  the  M2D  grid  from  geographic  coordinates. 
STWAVE  operates  on  a  grid  aligned  such  that  the  x-axis  is  directed  onshore  and 
the  y-axis  is  directed  alongshore.  Figure  10  shows  three  examples  of  M2D  and 
STWAVE  coordinates  for  different  shoreline  orientations.  Each  model  must  be 
independently  set  up  so  that  its  coordinate  system  is  consistent  with  its 
computational  approach.  For  coupling,  the  M2D  and  STWAVE  grids  overlap 
and  information  is  mapped  from  one  model  to  the  other.  SMS  automatically 
calculates  any  required  rotations  of  components  when  mapping  fields  between 
STWAVE  and  M2D. 
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Figure  10.  Example  M2D  and  STWAVE  grid  orientations 


Chapter  5  Model  Features 


In  areas  of  the  computational  domain  where  wave  breaking  or  strong  wave- 
current  interaction  takes  place,  resolution  for  M2D  and  STWAVE  should  be 
similar.  By  specifying  cells  in  both  models  to  have  similar  spacing,  coupling 
efficiency  is  maximized  because  high-resolution  details  calculated  by  one  model 
are  not  lost  when  the  solution  field  is  mapped  to  the  other  model.  Figure  1 1 
shows  STWAVE  and  M2D  grid  spacing  in  the  nearshore  area.  Surf  zone  width 
is  indicated  by  the  line  denoting  10  STWAVE  cells.  In  this  area,  M2D  and 
STWAVE  have  similar  spacing  in  the  cross-shore.  Cell  sizes  in  the  M2D  grid 
become  larger  seaward  of  the  surf  zone. 


Figure  11.  Example  M2D  and  STWAVE  grid  spacing 
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Coupling  M2D  and  STWAVE  requires  that  the  user  specify  the  steering 
interval,  or  elapsed  time  between  calls  to  STWAVE.  Selection  of  the  steering 
interval  is  dependent  on  the  processes  that  are  most  significant  to  the  goals  of  the 
modeling  effort.  A  smaller  steering  interval  tightens  coupling  between  the 
models,  increasing  accuracy.  However,  smaller  steering  intervals  require  more 
STWAVE  runs  and  thus  increase  the  overall  computation  time.  Thus,  the  user 
must  balance  the  cost  of  run  time  versus  accuracy. 

Temporal  scales  of  processes  being  modeled  also  play  a  role  in  the  selection 
of  the  steering  interval.  For  example,  if  a  mean  wave  condition  is  being  applied 
in  a  predominantly  tidal  situation  and  the  wave  properties  do  not  change  much 
over  time,  the  steering  interval  can  be  set  to  a  relatively  large  value.  If  a  storm  is 
being  modeled  and  full  coupling  between  STWAVE  and  M2D  is  required,  then 
the  steering  interval  should  be  set  to  a  smaller  value.  If  a  situation  is  studied  in 
which  there  is  strong  wave-current  interaction,  such  as  at  as  inlet,  then  a  shorter 
steering  interval  may  be  specified  to  capture  the  modification  of  the  waves  by  the 
tidal  current  and  the  time-varying  water  level.  Typical  steering  intervals  are  3  hr 
for  fair  weather  conditions,  and  for  storm  waves  the  steering  interval  should  be 
more  frequent.  Judgment  and  experience  must  be  exercised,  as  for  all  numerical 
models,  and  sensitivity  analysis  is  recommended  for  a  particular  application  to 
determine  the  most  appropriate  steering  interval. 


Output  Options 

M2D  provides  two  types  of  output  that  can  be  selected  by  the  user.  Time 
series  of  calculated  variables  at  specific  cells,  called  observation  cells,  can  be 
saved  at  user-specified  time  intervals.  Global  fields  can  be  written  at  user- 
specified  times. 

All  variables  are  output  at  their  computational  location  in  the  cell.  Thus, 
water  surface  elevation  is  at  the  cell  center,  the  ^-component  of  velocity  and  x- 
component  of  flow  rate  are  at  the  left  cell  face,  and  the  v-component  of  velocity 
and  y-component  of  flow  rate  are  at  the  bottom  cell  face. 


Observation  cell  time  series 

Time  series  of  water  surface  elevation,  w-component  of  velocity,  v- 
component  of  velocity,  x-component  of  flow  rate,  andy-component  of  flow  rate 
can  be  saved  at  observation  cells.  The  user  can  specify  any  number  of  cells  as 
observation  cells.  Any  combination  of  variable  output  may  be  selected  ranging 
from  one  to  all  five  previously  listed.  A  time  interval  for  output  must  be 
specified  and  the  most  accurate  output  is  achieved  if  the  output  interval  is 
specified  as  an  integer  multiple  of  the  calculation  time-step.  Observation  cell 
output  will  take  place  from  the  start  to  the  end  of  the  simulation.  The  SMS 
interface  provides  tools  for  specifying  all  aspects  of  the  observation  cell  output. 
Time  series  of  each  variable  selected  for  output  is  written  to  a  separate  file  and 
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values  for  all  observation  cells  are  included  in  that  file.  Chapter  7  describes  the 
format  and  provides  an  example  of  the  time  series  observation  cell  output  files. 


Global  field  output 

Global  output  of  water  surface  elevation  and  velocity  components  can  be 
written  at  user-specified  times.  Water  surface  elevations  are  written  to  a  separate 
file  from  the  global  velocities.  M2D  reads  a  file  containing  times  at  which  global 
output  is  specified  for  each  variable  (water  surface  elevation  or  velocity).  Thus, 
global  output  times  for  the  two  files  are  not  required  to  be  concurrent,  and  the 
increment  between  successive  times  does  not  have  to  be  constant.  By  specifying 
discreet  time  stamps,  the  user  has  flexibility  for  creating  global  files  with  more 
dense  temporal  resolution  during  certain  time  intervals.  The  SMS  interface 
provides  tools  for  specifying  all  aspects  of  the  global  output.  Chapter  7  describes 
the  format  and  provides  an  example  of  the  global  output  files. 
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Chapter  5  Model  Features 


6  Surface-Water  Modeling 
System  Interface  for  M2D 


A  graphical  interface  for  M2D  has  been  implemented  within  the  SMS 
Versions  8.0  and  higher  that  contains  tools  for  grid  development,  parameter 
specification,  control  file  setup,  boundary  specification  including  extraction  of 
water  surface  elevation  and/or  velocities  from  regional  models  such  as  ADCIRC, 
model  runs,  post-processing  of  global  field  values,  visualization,  and  coupling  of 
M2D  with  STWAVE  through  the  Steering  Module.  This  chapter  provides 
instruction  on  creating  and  working  with  M2D  projects  within  the  SMS.  Dialogs 
shown  are  from  SMS  8.1. 

Access  to  the  M2D  interface  is  obtained  through  the  2D  Cartesian  Grid 
Module  in  SMS.  The  Cartesian  Grid  Module  also  accesses  the  Map  Module  via 
an  M2D  Coverage.  The  interface  for  M2D  includes: 

a.  M2D  Coverage  and  Map  tools 

b.  Cartesian  Grid  Module  (tools  and  display  options) 

c.  M2D  Menu 

d.  Steering  Module 

Required  Information 

An  M2D  grid  is  a  Cartesian  Grid  with  cells  that  may  be  of  varying  sizes. 
Each  cell  has  a  location,  side  dimensions  ( Ax  and  Ay ),  and  depth.  Grid 
definition  within  SMS  includes: 

a.  A  geographic  location  -  the  position  of  the  first  cell  and  the  orientation 
of  the  grid. 

b.  Dimensions  -  domain  extent  and  number  of  cells  in  each  direction. 

c.  Cell  sizes  -  the  width  of  each  column  and  height  of  each  row  in  the  grid. 

d.  Depths  —  the  water  depth  at  the  center  of  each  cell. 
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The  SMS  interface  provides  tools  and  methodology  for  the  user  to  define 
each  of  these  components  and  to  develop  the  grid.  Depths  over  the  model 
domain  are  the  most  complex  component  of  the  grid  because  these  values  can 
represent  any  geometric  shape.  Bathymetric  information  is  provided  to  the  SMS 
by  the  user  as  either  a  constant  depth,  or  as  a  set  of  data  points  each  of  which  has 
a  depth  associated  with  it.  SMS  can  read  Digital  Elevation  Model  (DEM)  grids 
or  scattered  data  point  surveys  and  display  them  as  a  surface  to  show  the  area 
over  which  a  grid  will  be  generated.  A  typical  scattered  data  set  is  illustrated  by 
the  red  crosses  in  Figure  12.  SMS  interpolates  scattered  data  to  the  grid  to  define 
the  depths  at  each  cell.  For  more  information  on  scatter  data  sets  and  the 
Scattered  Data  Module  refer  to  the  SMS  Help  file  or  the  SHOALS  toolbox 
documentation  (Wozencraft  et  al.  2002). 

After  depth  values  are  defined,  the  user  specifies  the  position,  orientation  and 
extent  of  the  grid  using  a  rectangular  object  called  a  grid  frame.  Simple  grids 
with  constant-sized  cells  can  be  created  in  the  Cartesian  Grid  Module.  More 
complex  grids  are  created  in  the  Map  Module. 


Figure  12.  Grid  frame  around  scattered  data  points 


Grid  Generation  from  M2D  Coverage 

Most  grids  will  be  developed  within  the  Map  Module.  Information  in  the 
Map  Module  is  stored  in  layers  or  coverages.  Each  coverage  has  a  specific  type, 
which  defines  the  properties  of  the  information  stored  in  that  layer.  SMS 
includes  an  M2D  coverage  type  to  allow  the  definition  of  an  M2D  simulation. 
There  is  a  default  coverage  in  SMS  at  all  times.  This  coverage  can  be  used  to 
create  an  M2D  coverage  by  changing  its  type  or  a  new  coverage  with  type  M2D 
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can  be  created.  Either  of  these  options  can  be  invoked  by  issuing  the  Coverages 
command  in  the  Feature  Objects  menu  in  the  Map  Module.  By  changing  the 
default  coverage  to  be  an  M2D  coverage,  the  modeler  has  instructed  SMS  to 
create  M2D  grids  from  the  information  being  entered. 


Grid  frame  creation  and  editing 


With  an  M2D  coverage  active,  the  grid  frame  is  defined  by  selecting  the 


Create  Grid  Frame  tool  I  ***  .  When  this  tool  is  active,  clicking  in  the  main 
display  window  of  SMS  defines  the  position  and  extents  of  a  grid  frame.  The 
first  click  defines  the  origin  of  the  grid,  the  second  click  defines  the  bottom  edge 
of  the  grid  and  its  size  in  the  “I”  direction,  and  a  third  click  defines  the  size  of  the 
grid  frame  in  the  “J”  direction.  A  new  grid  frame  or  enclosing  shape  for  the  grid 
is  created  on  the  screen  (Figure  12).  This  grid  frame  can  be  moved,  rotated, 
enlarged  or  reduced  in  size  either  graphically  or  by  accessing  edit  windows 
before  the  grid  is  generated  to  fill  the  frame. 


To  edit  a  grid  frame,  the  modeler  selects  the  Select  Grid  Frame  tool  12SS  and 
clicks  on  the  grid  frame  to  be  edited.  Handles  appear  at  the  comers  and  sides  of 
the  selected  grid  frame  as  shown  in  Figure  12.  The  user  may  drag  any  of  these 
handles  to  change  the  size  and  position  of  the  grid  frame.  A  circular  handle  that 
extends  from  the  “F*  axis  of  the  grid  frame  can  be  dragged  to  change  the 
orientation  of  the  grid  frame.  The  following  graphical  editing  operations  and 
their  functions  are  available  when  a  grid  frame  is  selected: 


a.  Move  Frame  -  Click  the  box  located  at  the  center  of  the  frame  interior 
and  drag. 

b.  Resize  Frame  -  Click  a  highlighted  comer  or  edge  and  drag  to  resize. 

c.  Rotate  Frame  -  Click  inside  the  circle  near  the  bottom  right  comer  of  the 
frame  and  drag  to  rotate  the  frame. 

Grid  frame  parameters  can  also  be  explicitly  modified  using  the  edit  window  at 
the  top  of  the  screen.  These  parameters  are: 


a.  Grid  Origin  -  The  X  and  Y  edit  fields  at  the  top  of  the  screen  allow  the 
user  to  explicitly  specify  the  bottom  left  comer  location  of  the  grid 
frame. 

b.  Angle  of  rotation  -  The  angle  edit  field  at  the  top  of  the  screen  can  be 
used  to  set  the  angle  that  the  grid  frame  will  be  rotated  counterclockwise 
from  the  +x-axis.  This  angle  should  be  between  -45  and  45  deg. 

The  grid  frame  size  is  displayed  at  the  lower  edge  of  the  screen  as  it  is  being 
edited. 
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Grid  generation 


After  the  grid  frame  is  defined,  an  M2D  grid  is  generated  in  SMS  with  the 
Feature  Objects  \  Map  ->  2D  Grid  command.  This  command  opens  the  Map- 
>2D  Grid  dialog.  For  a  simple  grid  frame,  this  dialog  allows  the  user  to  specify 
the  number  of  cells  in  each  direction  (or  the  cell  size  in  each  direction)  and  the 
source  for  depth  data.  The  resulting  grid  will  consist  of  constant-sized  cells. 

M2D  allows  varying  cell  sizes  to  provide  greater  resolution  in  areas  where 
needed.  The  interface  provides  for  the  development  of  grids  with  greater 
resolution  in  specific  areas  through  the  creation  of  refine  points.  A  refine  point  is 

|*  .1 

produced  by  creating  a  feature  point  i.  * . J  at  the  location  where  specific  resolution 

is  to  be  assigned.  Double  clicking  on  the  feature  point  (with  the  Select  Feature 

Point  tool  —  active)  invokes  the  Refine  Point  attributes  dialog.  This  dialog 
allows  for  specification  of  cell  sizes  around  the  point,  spatial  change  in  cell  sizes 
with  distance  from  the  refine  point,  and  a  maximum  cell  size.  For  the  settings 
shown  in  Figure  13,  the  cell  around  the  refine  point  would  be  a  10-m  x  10-m  cell, 
the  cells  would  get  10  percent  bigger  with  each  row  or  column,  and  the  largest 
cell  would  be  20  m  x  20  m. 


Figure  13.  Map->  2D  Grid  and  Refine  Point  dialogs 

When  refine  points  are  present  in  the  M2D  coverage,  the  top  portion  of  the 
Map->2D  Grid  dialog  is  dimmed  out.  SMS  will  generate  cells  that  match  the 
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refine  point  specifications.  If  multiple  refine  points  are  present  and  conflict  with 
each  other,  cells  will  be  created  to  meet  the  criteria  of  all  refine  points  as  closely 
as  possible.  Figure  14  shows  a  grid  developed  with  a  refine  point  in  the  inlet  and 
cell  strings  around  the  grid  boundary. 


Figure  14.  SMS  generated  grid 

Each  cell  will  be  assigned  a  depth  based  on  the  depth  option,  and  cells  will 
be  assigned  to  be  land  or  water  based  on  the  resulting  depths.  However,  the 
modeler  may  force  islands,  or  other  coastline  features  into  a  grid  by  creating  arcs 

rl 

with  the  Create  Feature  Arc  tool  J.  These  arcs  will  then  represent  the 
coastline  in  the  M2D  coverage.  Attributes  of  the  arc  can  be  specified  by 

selecting  the  arc  with  the  Select  Feature  Arc  tool  &  .  and  then  clicking  on 
Feature  Objects  in  the  pull-down  menu,  then  entering  the  Attributes  dialog 
(Figure  15).  Cells  generated  along  this  arc  will  be  treated  as  specified  by  the  arc 
type.  By  default,  cells  intersected  by  these  coastline  arcs  are  classified  based  on 
the  percent  of  the  cell  on  the  “land”  side  (percent  preference  arc).  If  more  than 
half  the  cell  is  land,  the  cell  is  classified  as  land.  However,  in  some  situations, 
the  model  may  require  a  continuous  stretch  of  either  land  or  water  to  represent  a 
specific  shoreline  feature,  such  as  a  jetty  or  narrow  canal.  In  these  situations,  the 
coastline  arcs  may  also  be  flagged  as  “land”  or  “water”  preference.  Thus,  the 
three  options  for  arc  preferences  are: 

a.  Percent  preference:  If  more  than  50  percent  of  the  cell  through  which  the 
arc  cuts  is  land,  then  the  cell  will  be  land.  If  more  than  50  percent  of  the 
cell  is  water,  then  the  cell  will  be  water. 
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b.  Land  preference:  Forces  cells  lying  on  the  arc  to  be  land. 

c.  Water  preference:  Forces  cells  on  the  arc  to  be  water. 


CGrid  Arc  Options 


-Arc  Type- 


C  Generic  Arc 

(•  Percent  Preference  Coastline  Arc 
C  Land  Preference  Coastline  Arc 
r  Ocean  Preference  Coastline  Arc 


Help 


OK 


Cancel 


Figure  15.  Arc  options  for  generating  coastlines 

After  an  arc  type  is  specified,  selecting  the  arc  will  reveal  the  water  and  land 
sides  of  the  arc,  which  are  displayed  as  blue  and  brown  arrows,  respectively.  If 
the  water  and  land  sides  of  the  arc  are  opposite  from  what  they  should  be,  the  arc 
direction  can  be  reversed  by  clicking  Reverse  Arc  Direction  under  the  Feature 
Objects  pull-down  menu. 

The  Map->2D  Grid  command  also  creates  cell  strings  across  all  ocean 
boundaries  of  the  grid.  These  strings  are  described  in  the  following  section  and 
are  tools  for  assigning  boundary  conditions  for  the  numerical  model  run. 


Cartesian  Grid  Module 

The  2D  Cartesian  Grid  Module  .§1 !  contains  tools  for  editing  2D  Cartesian 
finite  difference  grids.  These  grids  consist  of  cells  aligned  with  a  rectilinear 
coordinate  system.  An  existing  grid  can  be  read  in  from  an  M2D  simulation  file, 
or  created  through  the  Map  Module.  With  a  grid  in  memory,  the  following  tools 
are  available  to  edit  the  grid: 


Select  Cell 


The  Select  Cell  tool  is  used  to  select  a  grid  cell.  A  single  cell  is  selected  by 
clicking  on  it.  A  second  cell  can  be  added  to  the  selection  list  by  holding  the 
SHIFT  key  while  selecting  it.  Multiple  cells  can  be  selected  at  once  by  dragging 
a  box  around  them.  A  selected  cell  can  be  de-selected  by  holding  the  SHIFT  key 
as  it  is  clicked. 


50 


Chapter  6  Surface-Water  Modeling  System  Interface  for  M2D 


When  a  single  cell  is  selected,  its  Z  coordinate  is  shown  in  the  Edit  Window. 
The  Z  coordinate  can  be  changed  by  typing  a  new  value  in  the  edit  field,  which 
updates  the  depth  function.  If  multiple  cells  are  selected,  the  Z  coordinate  field  in 
the  Edit  Window  shows  the  average  depth  of  all  selected  cells.  If  this  value  is 
changed,  the  new  value  will  be  assigned  to  all  selected  cells. 

With  one  cell  selected,  the  Edit  Window  shows  the  cells  ij  location.  With 
multiple  cells  selected,  the  Edit  Window  shows  the  number  of  selected  cells. 


Select  Row/ 


Select  Column 


The  Select  Row  and  Select  Column  tools  are  used  to  select  cell  rows  and 
columns.  Multiple  rows  and  columns  are  selected  in  the  same  manner  as 
selecting  multiple  individual  cells:  holding  the  SHIFT  key,  etc. 


11*11  Insert  Column/ H=  Insert  Row 

When  the  Insert  Column  or  Row  tools  are  active,  clicking  within  a  cell  splits 
the  row/column  containing  the  selected  cell,  creating  a  new  row  or  column  in  the 
grid.  The  Z-values  of  all  split  cells  are  the  same  as  the  original  cells  values. 


Drag  Column/ Drag  Row  Boundary 


The  position  of  the  edge  of  rows  or  columns  in  a  grid  can  be  changed  with 
the  Drag  Column  or  Row  tools.  These  tools  make  one  column/row  narrower 
while  making  its  neighbor  wider. 

These  tools  allow  for  manual  specification  of  the  resolution  in  specific 
portions  of  the  grid.  Note  that  depth  values  are  not  adjusted  so  significant 
dragging  of  boundaries  should  be  avoided,  or  depths  should  be  reinterpolated 
after  the  boundaries  are  modified. 


m  Create  Cell  String 

The  Create  Cell  String  tool  allows  the  modeler  to  group  a  string  of  cells 
together  for  the  purpose  of  assigning  boundary  conditions.  Cell  strings  are 
created  automatically  around  water  boundaries  when  a  grid  is  generated.  The 
user  may  create  others  as  desired  or  delete  and  replace  the  automatically- 
generated  cell  strings.  When  the  Create  Cell  String  tool  is  active,  the  modeler 
selects  each  cell  to  be  added  to  the  string.  By  holding  down  the  SHIFT  key,  all 


Chapter  6  Surface  Water  Modeling  System  Interface  for  M2D 


51 


boundary  cells  between  the  previously  selected  cell  and  the  selected  cell  are 
added  to  the  cell  string. 


Select  Cell  String 


To  specify  a  boundary  condition,  the  modeler  must  create  a  cell  string  over 
the  desired  region,  and  then  select  the  cell  string  while  the  Select  Cell  String  tool 
is  active.  Boundary  conditions  applied  to  the  selected  cell  string  are  assigned 
through  the  Assign  BC  dialog,  which  is  accessed  through  the  M2D  pull-down 
menu. 


M2D  Menu 

The  M2D  menu  includes  commands  for  managing  the  simulation.  The 
management  operations  are  editing  boundary  conditions  and  cell  attributes, 
checking  the  simulation  for  common  errors,  and  running  a  model.  Commands 
from  the  menu  are  explained  in  the  following  sections: 


Delete  Simulation 

The  Delete  Simulation  command  deletes  the  2D  grid  and  all  information 
associated  with  it. 


Assign  BC 

The  Assign  BC  command  allows  the  user  to  assign  a  boundary  condition  to 
the  cell  string  through  the  M2D  Boundary  Conditions  dialog  (Figure  16).  This 
command  is  only  active  if  a  cell  string  is  first  selected. 

Boundary  conditions  specified  within  this  dialog  include  the  following: 

a.  Unassigned  Boundary:  When  a  cell  string  is  created,  the  string  receives 
this  assignment.  This  designation  is  not  a  boundary  condition,  but  rather 
indicates  that  the  boundary  has  not  been  assigned  yet  and  has  no 
influence  on  the  model. 

b.  Flow  Rate-forcing:  This  type  of  boundary  condition  allows  the  modeler 
to  define  a  time  series  of  flow  rates  to  be  prescribed  at  the  boundary. 

The  time  series  associated  with  this  boundary  contains  a  list  of  times  and 
flow  rates  in  m3/s  to  be  applied  at  boundary  cells.  Each  cell  contained  in 
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v M2D  Boundary  Conditions 


Boundary  Conditions - 

C  Unassigned  Boundary 

C  Row  Rate-forcing 

<*  V/SE-forcing 

C  Tidal  Constituent-forcing 

r  Extract  WSE  andVel 


Time  Series' - 

(•  Define  curve 

Curve  undefined. 


C  Extract  from  data  set 


P  Interpolate  between  times 


Browse  for  file 


Help 


OK  |  Cancel 


Figure  16.  M2D  Boundary  Conditions  dialog 

the  cell  string  will  have  the  prescribed  flow  rate.  Time  series  can  be 
developed  within  SMS  by  entering  the  Define  Curve  dialog. 
Alternatively,  a  pre-existing  file  can  be  assigned  by  clicking  on  the 
Browse  for  file  tab.  If  the  Interpolate  box  is  checked,  M2D  linearly 
interpolates  between  flow  rate  values  at  every  time-step.  If  the 
Interpolate  box  is  not  checked,  boundary  flow  rate  values  are  only 
updated  at  the  times  that  they  are  provided  in  the  input  file. 

c.  WSE-forcing:  This  type  of  boundary  condition  allows  the  modeler  to 
define  a  time  series  of  water  level.  The  time  series  associated  with  this 
boundary  contains  a  list  of  times  and  water  levels  in  meters  to  be 
prescribed  along  the  boundary.  The  Interpolate  between  times  checkbox 
instructs  M2D  on  how  the  time  series  water  level  information  is  to  be 
treated  within  M2D  when  forcing  a  boundary.  If  the  Interpolate  box  is 
checked,  M2D  linearly  interpolates  between  water  level  values  at  every 
time-step.  If  the  Interpolate  box  is  not  checked,  water  level  values 
applied  as  boundary  conditions  are  only  updated  at  the  times  that  they  are 
provided  in  the  input  file.  Two  options  for  assigning  a  water  surface 
elevation  boundary  condition  are  available  as  follows: 

(1)  Single  time  series  across  a  boundary:  Time  series  of  water 

surface  elevation  can  be  developed  with  SMS  by  clicking  on  the 
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Define  Cuiwe  button.  Alternately,  a  pre-existing  file  can  be 
assigned  by  clicking  on  the  Browse  file  tab. 


(2)  Multiple  time  series  across  a  boundary:  SMS  detects  if  a 

regional  model  such  as  ADCIRC  and  its  global  water  surface 
elevation  solution  are  loaded,  and  activates  the  extract  from  data 
set  capability  as  a  possible  source  of  the  boundary  condition. 
When  the  boundary  condition  is  assigned  to  be  an  extracted 
boundary  condition,  SMS  prompts  the  user  to  specify  the  source 
of  the  extracted  information  (a  functional  data  set  from  the 
regional  model)  using  the  Extracted  Boundary  Condition  dialog. 
Extraction  of  water  surface  elevations  is  available  for 
specification  of  boundary  conditions  from  any  regional  2-D 
model  that  can  be  brought  into  SMS. 

d.  Tidal  Constituent-forcing:  These  boundary  conditions  apply  up  to  eight 
tidal  constituents  to  force  water  surface  elevations  along  the  selected  cell 
strings.  Tidal  constituents  are  specified  within  the  M2D  Tidal 
Constituent  dialog  accessed  in  the  Model  Control  dialog. 

e.  Extract  WSE  and  Vel  forcing:  For  this  boundary  condition  type,  SMS 
detects  if  a  regional  model,  such  as  ADCIRC,  and  its  global  water 
surface  elevation  and  velocity  solution  files  have  been  loaded,  and 
activates  the  extract  capability  as  a  possible  source  of  the  boundary 
condition.  When  the  boundary  condition  is  assigned  to  be  an  extracted 
boundary  condition,  SMS  prompts  the  user  to  specify  the  source  of  the 
extracted  information  (a  functional  data  set  from  the  regional  model) 
using  the  Extracted  Boundary  Condition  dialog.  Both  water  surface 
elevation  and  velocity  from  the  regional  model  must  be  present  to  extract 
values  for  this  boundary  type.  Extraction  of  water  surface  elevations  and 
velocities  is  available  for  specification  of  boundary  conditions  from  any 
larger-domain  2-D  model  that  can  be  brought  into  SMS. 

File  formats  for  use  with  M2D  are  described  in  Chapter  7  and  Appendix  A. 


Delete  BC 

The  Delete  BC  command  allows  the  user  to  delete  the  boundary  condition 
assigned  to  a  cell  string.  A  cell  string  must  be  selected  to  activate  this  command. 


Assign  Cell  Attributes 

The  Assign  Cell  Attributes  command  (Figure  17)  allows  the  modeler  to  set 
the  status  for  one  or  more  selected  cells.  A  cell  can  be  active  (water),  inactive 
(land),  or  observation.  Observation  cells  are  numerical  stations  and  assigned  to 
be  active.  Bottom  roughness  can  also  be  specified  through  this  dialog. 
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Figure  17.  Assign  Cell  Attributes  dialog 

Observation  cells  can  be  assigned  so  that  M2D  will  write  time  series  of  water 
surface  elevation  and  velocity,  and/or  flow  rate  output  files.  Settings  for  output 
files  written  for  observation  cells  are  specified  in  the  Output  Control  portion  of 
the  Model  Control  dialog  discussed  later  in  this  chapter. 


Merge  Cells 

The  Merge  Cells  command  allows  the  modeler  to  merge  consecutive  rows  or 
columns  into  one.  The  command  is  enabled  only  if  rows  or  columns  have  been 
selected  with  the  appropriate  tool  (select  row  or  column). 


Model  Check 

The  Model  Check  command  performs  a  number  of  checks  on  the  simulation 
to  ensure  a  valid  model.  These  checks  are: 

a.  All  water  boundaries  have  boundary  conditions  specified. 

b.  Cell  aspect  ratio  is  no  greater  than  2. 

c.  Maximum  time-step  size  is  suggested  according  to  an  internal  calculation 
made  within  SMS. 

d.  Correct  model  control  specifications  (i.e.,  if  a  tidal  boundary  exists,  make 
sure  that  tidal  constituents  have  been  defined  for  forcing). 
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Model  Control 
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The  Model  Control  command  displays  the  Model  Control  dialog  (Figure  18). 
Input  and  output  file  names  are  specified  from  within  the  M2D  Model  Control. 

In  addition,  the  user  defines  the  time  control  associated  for  the  simulation  from 
within  the  Model  Control.  A  wind-forcing  file  can  also  be  assigned  from  within 
the  Model  Control.  Options  within  this  dialog  include  the  following: 


M2D  Model  Control 


Optional  input  Res - - - - - - 

r  Initial  Conditions  File  il 

F  Wind  File  Clll  wind.m2w 

PI  Time  Specification  File  For  Vector  Plot  Output  Lj| 

F  Time  Specification  File  For  Global  Elevation  Output  Uj]  canaLCGrid1_E.m2t 


j-  Hot  Start1 . . : . . 

I  F  Write  Hot  Start  Output  File 


!  F  Automatic  Recurring  Hot  Start  File 


File  Prefix 


Time  to  Write  Out  0.0 


Interval  124.0 


r  Output  Files - 

|  F  G  bbal  Velocity  [*.m2v) 

I  F  Global  Elevation  f.nn2s) 


File  Prefix 


jvel 

jelev 


Sediment  Transport - 

r  Calcuiate  Sediment  T ramport 


I  ransposi F; ate  Prer-s:  I1-  'aV'I  [ 


I  tsrsL':'  Step  jo 0 


Wind  Control... 

Chcjose  Time... 


Choose  Time... 


Parameters... 


Time  Control- 


Output  Control... 


Tidal  Constituents.., 


Radiation  Stresses - - — - - r— — 

f“  Include  STWAVE  Radiation  Stresses 

sV-n  Stiej;  Input  Re  Cjl  ■ 


Help 


OK 


Cancel 


Figure  18.  M2D  Model  Control  dialog 


Optional  input  files.  Although  not  required,  externally-generated  input  files 
can  be  accessed  in  the  simulation.  By  turning  on  the  toggle  next  to  each  input 
file  type,  an  already-existing  file  can  be  selected  by  clicking  on  the  File  Browse 
button.  If  none  exists,  the  user  can  manually  create  the  input  file  by  clicking  on 
the  button  to  the  right  that  identifies  each  file  type.  For  example,  in  Figure  18,  a 
wind  input  file  will  be  read  by  M2D  and  it  is  called  “wind.m2w.”  Alternatively, 
the  user  can  specify  the  wind  information  by  entering  the  Wind  Control  dialog. 

Initial  conditions  (*.m2i).  The  initial  conditions  file  contains  a  line  for 
every  cell  in  the  grid  containing  information  on  the  state  and  status  of  each  cell. 
This  information  includes  cell  identification  number,  depth,  water  surface 
elevation,  u-  and  v-components  of  velocity,  dr \/  8t ,  and  u  ’  and  v  ’  (solutions  of 
Equations  100  and  105).  Status  of  cell  activity  and  boundaries  are  also  provided. 
A  full  description  of  the  initial  conditions  file  is  given  in  Chapter  7. 


Chapter  6  Surface-Water  Modeling  System  Interface  for  M2D 


Wind  (*.m2w).  The  wind  file  contains  a  list  of  time-steps  containing  wind 
magnitude  and  direction.  Each  line  contains  three  values:  time  (hours), 
magnitude  (m/s),  direction  from  (deg).  Wind  directions  are  referenced  as  from 
north  =  0  deg,  from  east  =  90  deg,  etc.  Note  that  this  wind  direction  convention 
is  different  from  the  convention  described  for  the  governing  equations 
(Chapter  2).  M2D  converts  the  wind  velocity  from  the  input  file  convention  to 
the  computation  convention  internally.  Clicking  the  Wind  Control  button  brings 
up  a  dialog  where  wind  magnitude  and  direction  time  series  can  be  specified. 

Time  specification  for  vector  plot  output  (*_V.m2t).  The  Time 
Specification  dialog  allows  the  user  to  specify  time  stamps  for  global  solution 
output  (in  hours).  The  vector  plot  output  time  specification  corresponds  to  the 
global  velocity  solution  file  (*.m2v).  Time  increments  between  global  output 
can  vary,  allowing  the  user  to  have  more  or  less  frequent  output. 

Time  specification  for  global  elevation  output  (*_E.m2t).  The  Time 
Specification  dialog  allows  the  user  to  specify  time  stamps  for  global  solution 
output  (in  hours).  The  scalar  plot  output  time  specified  is  associated  with  the 
times  at  which  M2D  will  write  out  the  global  elevation  file  (*.m2s).  Time 
increments  between  global  output  can  vary,  allowing  the  user  to  have  more  or 
less  frequent  output. 

Hot  start.  Two  independent  hot  start  options  are  available  for  M2D. 
Checking  the  Write  Hot  Start  Output  File  box  allows  the  user  to  specify  a  time  at 
which  a  file  of  the  same  format  as  the  initial  conditions  file  will  be  written.  The 
hot  start  file  can  be  later  used  as  an  initial  conditions  file  for  subsequent  model 
runs.  The  user  specifies  a  prefix  for  the  hot  start  file  name  and  the  elapsed  time, 
in  hours,  at  which  the  file  will  be  written.  By  checking  the  Automatic  Recurring 
Hot  Start  File  box  and  providing  a  time  interval  (hours),  hot  start  files  will  be 
written  at  the  time  interval  specified.  Hot  start  files  are  written  with  file  names 
alternating  with  HOTSTART1  .M2I  and  HOTSTART2.M2I.  These  files  can  be 
later  input  as  initial  conditions  files  for  a  subsequent  simulation.  The  file 
HOTSTART.INFO  is  also  written  and  contains  the  name  (HOTSTART1.M2I  or 
HOTSTART2.M2I)  and  time  of  the  last  saved  hot  start  file. 

Global  velocity  output  (*.m2v).  By  checking  this  toggle  box,  a  global 
velocity  solution  will  be  written  out  by  M2D  at  the  times  specified  in  the  M2D 
Output  Time  Specification  dialog  for  Vector  Plot.  The  file  extension  “.m2v”  is 
appended  to  the  prefix  specified.  The  global  velocity  file  format  contains  a  line 
with  the  time-step,  followed  by  subsequent  lines  for  each  grid  cell  with  four 
values:  x-position  in  present  coordinate  system,  y-positi  on  in  present  coordinate 
system,  w-component  of  velocity,  and  v-component  of  velocity.  Position  values 
have  units  of  meters  and  velocity  values  have  units  of  m/s. 

Global  elevation  output  (*.m2s).  The  explanation  provided  for  the  Global 
Velocity  applies  here  as  well,  with  the  difference  being  that  a  global  elevation 
solution  will  be  written  out.  The  global  elevation  file  format  is  the  same  as  that 
of  the  global  velocity  solution  file,  with  the  exception  that  the  u-  and  v- 
component  velocity  values  are  replaced  by  the  water  level  in  meters  at  each  cell. 
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Global  bottom  change  output  (*.m2s).  The  file  written  out  for  the  global 
bottom  change  file  is  associated  with  sediment  transport.  This  file  also  contains 
the  “,m2s”  extension,  so  the  prefix  should  be  different  from  that  for  the  global 
elevation  solution  file.  The  format  is  the  same  as  the  global  elevation  file,  except 
that  the  water  level  value  at  each  cell  is  replaced  by  the  depth  in  meters. 

Parameters.  The  Parameters  button  invokes  a  Model  Parameters  dialog 
that  allows  specification  of  anemometer  height,  the  ratio  of  air  to  water  density, 
the  latitude  of  the  grid,  momentum  equation  options,  and  wetting/drying 
parameters.  Standard  anemometer  height  is  10  m,  but  data  may  be  obtained  from 
an  anemometer  installed  at  a  different  height,  which  can  be  specified  in  the 
Model  Parameters  dialog.  The  ratio  of  air  to  water  density  is  0.0012  and  should 
not  be  modified.  Momentum  equation  options  let  the  user  specify  whether  or  not 
to  include,  independently,  the  advective  and  diffusion  terms.  Wetting  and  drying 
options  are  to  allow  wetting  and  drying  and  to  set  the  depth  at  which  cells  are 
considered  dry,  usually  in  the  range  of  0.05  to  0.08  m. 

Time  control.  The  Time  button  invokes  a  Time  Control  dialog  that  allows 
specification  of  the  start  date  and  time,  simulation  duration,  ramp  duration,  and 
the  time-step.  SMS  can  compute  a  theoretical  maximum  time-step  based  on 
celerity.  Practical  application  of  M2D  requires  that  the  time-step  be  less  than  the 
theoretical  maximum.  A  general  guideline  is  to  set  the  time-step  to  half  of  the 
theoretical  maximum,  and  then  adjust  the  time-step  according  to  the 
hydrodynamic  properties  of  the  simulation. 

Output  control.  The  Output  Control  button  invokes  an  Output  Control 
dialog  that  allows  specification  of  output  frequency,  and  what  variables  are  to  be 
output  for  time  series  and  flow  rates.  This  dialog  sets  the  output  control  for 
Observation  cells. 

Tidal  constituents.  The  Tidal  Constituents  button  invokes  a  Tidal 
Constituent  dialog  that  allows  the  specification  of  tidal  constituents  to  be 
assigned,  and  their  local  amplitudes  and  phases.  Amplitude  and  phase  is  held 
spatially  constant  along  an  entire  cell  string  for  each  tidal  constituent.  Phase 
must  be  specified  in  the  same  time  zone  as  other  model  inputs. 


Run  M2D 

The  Run  M2D  command  makes  sure  the  current  simulation  is  saved  to  disk, 
and  launches  M2D  to  run  the  present  simulation. 


Steering  Module 

Coupling  of  M2D  with  STWAVE  is  conducted  through  the  Steering  Module. 
This  feature  controls  interaction  of  the  two  models  by  alternating  STWAVE  and 
M2D  runs  for  a  specified  time,  called  the  Steering  Interval,  and  provides  mapped 
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fields  of  variables  to  each  model.  Seven  interaction  options  for  steering  the  two 
models  are  available  and  described  as  follows: 


a.  1  -way  steering:  radiation  stress  gradients  from  STWAVE  provided  to 
M2D. 


b. 


c. 


d. 


1-way  steering: 

1-way  steering: 

1-way  steering: 
STWAVE. 


currents  from  M2D  provided  to  STWAVE. 
total  depths  from  M2D  provided  to  STWAVE. 
total  depth  and  currents  from  M2D  provided  to 


e.  2-way  steering:  radiation  stress  gradients  from  STWAVE  provided  to 
M2D  and  currents  from  M2D  provided  to  STWAVE. 


f  2-way  steering:  radiation  stress  gradients  from  STWAVE  provided  to 
M2D  and  total  depth  from  M2D  provided  to  STWAVE. 

g.  2-way  steering:  radiation  stress  gradients  from  STWAVE  provided  to 
M2D  and  currents  and  total  depth  from  M2D  provided  to  STWAVE. 


The  user  controls  the  steering  options  by  checking  boxes  in  the  Steering  Module 
dialog  for  each  type  of  interaction  needed  for  the  specific  simulation  (Figure  19). 

To  invoke  the  Steering  Module,  M2D  and  STWAVE  files  must  be  loaded 
into  SMS.  All  inputs  and  options  for  both  models  must  be  specified  before 
launching  the  steering  process.  Users  should  consult  the  STWAVE  User’s 
Manual  (Smith  et  al.  1999,  2001)  for  information  on  setting  up  STWAVE  in 
SMS. 


The  Steering  Module  dialog  is  opened  from  the  Data  drop-down  menu 
(Figure  19).  The  steering  interval  is  set  by  specifying  the  time  requested  by  the 
“Run  STWAVE  every”  inquiry.  Interaction  between  the  models  is  selected  by 
clicking  the  available  options  in  the  M 2 D -A  STWAVE  (meaning  M2D  passes 
velocities  and/or  total  depth  to  STWAVE)  and  STWAVE -^M2D  (meaning 
STWAVE  passes  wave  information  to  M2D)  portions  of  the  dialog. 
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Ifteering, Module  ••  H 


Model  steering  to  perform:  j  M2D  <=>  ST  WAVE 


T  otal  simulation  time:  82.  DO  H  ours 

M 2D  Time  Control 


Run  ST  WAVE  every  J3.0 


hours 


M2D->STWAVE 

H  Energy 

Cl  Current  field 


I 15?]:  Water  Surface  Elevation 


STWAVE*>M2D 


E  jWavedata'  Extrapolation:  Settozero  * 


ExtraDOfation  distance:  |0.u0 


Help 


M2D  Location  STWAVE  location]  HPCS 
START  Jj 


Cancel 


Figure  19.  Steering  Module  dialog 

Locations  of  the  M2D  and  STWAVE  models  (executables)  are  specified 
through  the  M2D  Location  and  STWA  VE  Location  commands.  After  the  Steering 
Module  setup  is  complete,  clicking  Start  invokes  the  steering  process  and  a 
progress  screen  will  be  shown. 

During  steering,  SMS  creates  two  output  files  that  provide  information  on  the 
steering  process  and  on  the  model  progress.  The  file  “steeringstatus.txt”  provides 
information  on  the  steering  options  and  status  of  the  steering  process.  The  file 
“screenoutput.txt”  contains  text  that  M2D  and  STWAVE  write  to  the  screen. 
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7  Model  Setup  and  File 
Structure 


Setup  of  M2D  requires  development  of  a  computational  grid  and  preparation 
of  one  or  more  input  files.  The  SMS  creates  all  model  input  files  in  the  correct 
format  so  that  editing  or  input  file  generation  is  generally  not  required.  The  only 
exceptions  to  this  are  preparation  of  time  series  of  wind  speed  and  direction, 
water  level,  or  flow  rate  files  for  input  as  forcing.  These  files  can  be  created 
within  the  SMS,  but  often  the  user  has  data  from  which  these  files  are  developed. 
This  section  describes  the  structure  of  files  required  to  run  the  M2D  model  and 
its  output  files  to  assist  the  user  in  understanding  the  file  formats.  All  input  and 
output  files  to  M2D  are  ASCII.  Unless  otherwise  noted,  files  are  free  format. 


Input  Files 

Required  input  files  for  M2D  are  the  grid  and  control  files.  A  particular 
simulation  may  require  additional  input  files  that  may  include  any  combination 
of:  initial  conditions,  water  level  time  series,  flow  rate  time  series,  tidal 
constituents,  wind  speed  and  direction,  waves  stress,  and  output  specification  (for 
both  selected  cells  and  global  values).  The  structure  of  these  input  files  is 
described  here.  Sample  files  are  provided  in  Appendix  A. 


Grid  file 

The  grid  file  for  M2D  is  structured  such  that  all  information  pertaining  to  a 
cell  is  found  on  the  same  line  as  the  cell  identification  number.  This  format  is 
convenient  for  the  user  so  that  once  a  cell  is  located  in  the  grid  file,  its  properties 
are  easily  viewed  or  modified.  The  grid  file  contains  information  that  is  not  used 
within  M2D,  but  is  retained  for  user  reference  and  post-processing. 

The  first  line  of  the  grid  file  is  a  header  line  that  describes  the  columns  of 
information  that  make  up  the  grid.  Only  one  line  is  allowed  for  the  header.  All 
lines  after  the  first  specify  cell  information.  Cells  are  defined  by  their  cell 
identification  number  and  the  cell  numbers  of  adjacent  cells,  referred  to  by  local 
direction  (north,  east,  south,  west).  These  directions  are  relative  to  the  local 
(grid)  coordinate  system  defined  by  the  grid,  which  may  or  may  not  be  aligned 
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with  global  geographic  coordinates.  For  example,  if  the  grid  is  oriented  with  its 
y-axis  parallel  to  north-south,  then  the  grid  coordinate  system  is  aligned  with 
global  geographic  coordinates.  If  the  grid  is  rotated  at  an  angle  such  that  its  y- 
axis  is  not  parallel  to  north-south,  then  the  local  coordinate  system  is  not  aligned 
with  global  geographic  coordinates.  In  the  latter  case,  directions  specified  in  the 
grid  file  and  within  M2D  correspond  to  the  local  coordinate  system. 

Each  line  describing  a  cell  consists  of  the  following  information: 

Cell  number,  NC,  EC,  SC,  WC,  NB,  EB,  SB,  WB,  IACTV,  DX,  DY,  H,  N, 
ROW,  COL,  LAT,  X-DIST,  Y-DIST 

where  descriptions  of  parameters  are  given  in  Table  3.  Details  of  the  cell  activity 
parameter  IACTV  are  given  in  Table  4. 


Table  3 

Definitions  of  Parameters  in  Grid  File 


Parameter 

Description1 

Cell  Number 

Cell  identification  number  (referred  to  as  ICELL  within  M2D) 

NC 

Cell  number  of  cell  adjacent  to  and  north  of  ICELL 

EC 

Cell  number  of  cell  adjacent  to  and  east  of  ICELL 

SC 

Cell  number  of  cell  adjacent  to  and  south  of  ICELL 

WC 

Cell  number  of  cell  adjacent  to  and  west  of  ICELL 

NB 

Boundary  type  at  northern  edge  of  ICELL 

EB 

Boundary  type  at  eastern  edge  of  ICELL 

SB 

Boundary  type  at  southern  edge  of  ICELL 

WB 

Boundary  type  at  western  edge  of  ICELL 

IACTV 

Cell  type  or  active  status 

DX 

Cell  width  parallel  to  the  x-axis  (m) 

DY 

Cell  width  parallel  to  the  y-axis  (m) 

H 

Still-water  depth  relative  to  a  user-specified  datum  (m) 

N 

Manning  roughness  coefficient  (m/s1/3) 

ROW 

Row  position  of  cell2 

COL 

Column  position  of  cell2 

LAT 

Latitude  (decimal  degrees) 

X-DIST 

X  coordinate  or  distance  from  grid  origin  (m)3,4 

Y-DIST 

/coordinate  or  distance  from  grid  origin  (m)3,4 

1.  Directional  description  (north,  east,  south,  west)  refers  to  the  grid  coordinate  system 

2.  Parameter  is  not  applied  in  M2D  calculations 

3.  Parameter  is  not  applied  in  M2D  calculations,  but  is  written  in  global  output  files 

4.  Coordinates  are  located  at  cell  centers 
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Table  4  1 

Cell  Types  and  their  Function  in  M2D  | 

Type 

Index 

Type 

Function 

0 

Inactive 

Cell  not  included  as  part  of  calculation  domain 

1 

Active  regular  cell 

Non-forcing,  regular  cell 

2,6 

Water-level  forcing  boundary  cell 

Water  level  specified  as  a  boundary  condition  at 
this  cell.  Type  indices  of  2  and  6  denote 
whether  the  forcing  file  contains  an  individual 
time  series  (Type  Index  =  2)  or  multiple  time 
series  (Type  Index  =  6). 

3 

Flow-rate  forcing  boundary  cell 

Flow  rate  specified  as  a  boundary  condition  at 
this  cell 

5 

Tidal-constituent  forcing  boundary  cell 

Water-level  specified  through  tidal  constituents 
as  a  boundary  condition  at  this  cell 

7 

Mixed  water  level  and  velocity  forcing 
cell 

Water  level  and  velocity  applied  as  boundary 
condition  at  this  cell.  Requires  multiple  time 
series  file. 

Cell-center  coordinates  (x-dist  and  y-dist)  can  be  given  in  any  Cartesian 
coordinate  system,  such  as  State  Plane  or  UTM.  M2D  does  not  apply  the  cell- 
center  coordinates  in  calculations,  but  does  export  the  values  in  global  files  of 
water  surface  elevation  and  velocity.  Because  no  specific  coordinate  system  is 
required,  the  user  can  apply  a  coordinate  system  that  is  convenient  for  the 
particular  application. 

A  grid  file  is  required  for  all  M2D  projects.  SMS  saves  M2D  grid  files  with 
the  extension  “  m2g.” 


Model  control 

Model  control  specifications  are  defined  in  an  input  file  called  “m2d.m2c”  or 
“projectname.m2c”  where  “projectname”  is  given  to  SMS  by  the  user.  SMS 
saves  the  control  file  as  “m2d.m2c”  and  as  “projectname. m2c.”  Each  line  of  the 
control  file  contains  the  parameter  or  character  string  followed  by  a  description. 
The  description  is  optional  as  M2D  does  not  read  it.  File  names  for  input  and 
output  are  user-specified  for  M2D,  with  the  exception  of  the  alternating  hot-start 
files,  and  are  listed  as  input  parameters  in  the  control  file.  Names  of  files  are 
limited  to  50  characters  in  length.  There  must  be  at  least  one  space  between  the 
parameter  or  character  string  and  the  description.  Information  contained  in  the 
control  file  is  listed  in  Table  5  in  the  required  order.  The  format  of  the  control 
file  is  the  same  for  all  model  and  project  configurations.  All  parameters  listed  in 
Table  5  must  be  included  in  the  control  file. 

Two  types  of  output  files  can  be  specified:  time-series  of  variables  at 
specified  cells  and  global  values  of  variables  at  specified  times.  To  specify  time- 
series  of  variables,  cell  numbers  are  identified  at  locations  to  output  information 
and  a  separate  file  is  created  to  save  each  variable.  Files  denoted  in  Table  5  as 
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“Cell-specification  files”  list  cell  identification  numbers  at  which  time  series 
information  is  stored.  Each  line  of  a  cell-specification  file  contains  one  cell 
identification  number. 

Files  denoted  in  Table  5  as  “Time-specification  files”  are  for  global  velocity 
and  elevation  output,  and  contain  a  list  of  times  to  save  data.  Times  are  specified 
as  elapsed  hours  since  the  beginning  of  the  simulation.  Each  line  in  the  file 
contains  one  value  of  time  and  times  must  be  in  sequential  order.  The  interval 
between  successive  outputs  can  vary  through  the  simulation.  For  example,  a  time 
specification  file  may  have  output  times  prescribed  as  0,  1,  2,  2.5,  3,  3.5,  4,  4.25, 
and  5  hr. 


Table  5 

Model  Control  File  Specifications 

Parameter 

Description 

Version 

M2D  Version  number 

Anemometer  height  (m) 

Height  of  anemometer  above  water  or  land 
surface 

|  Ratio  of  density  of  air  to  density  of  water 

Set  to  0.0012  for  typical  applications 

Angle  between  true  north  and  y-axis  of  grid 
(deg) 

Defined  by  grid  orientation 

Grid  origin  x-coordinate 

Location  of  x  position  of  cell  1 

Grid  origin  y-coordinate 

Location  of  y  position  of  cell  1 

Time-step  (s) 

Model  time-step 

Automated  hot-start  interval  (hr) 

Time  interval  between  automated  hot-start  file 
writes 

Include  advective  terms 

Flag  for  inclusion  of  advective  terms  in  the 
momentum  equation.  Flag  settings:  0  =  do  not 
include,  1  =  include 

Include  mixing  terms 

Flag  for  inclusion  of  mixing  terms  in  the 
momentum  equation.  Flag  settings:  0  =  do  not  j 
include,  1  =  include  J 

Allow  wetting  and  drying 

Flag  for  allowing  flooding  and  drying.  Flag 
settings:  0  =  do  not  allow,  1  =  allow. 

Depth  (m)  to  begin  drying  cells 

If  wetting  and  drying  are  allowed,  drying  will 
occur  if  the  total  depth  in  a  cell  is  less  than  or 
equal  to  the  depth  specified  here. 

Calculate  sediment  transport1 

Flag  for  calculation  of  sediment  transport.  Flag 
settings:  0  =  do  not  calculate,  1  =  calculate 

Sediment  transport  time-step1 

Time-step  for  sediment  transport  calculations 

Starting  Julian  Day  (YYDDD  OR  DDD) 

Date  of  beginning  of  simulation 

Start  time  (hr) 

Time  of  beginning  of  simulation  J 

Realization  time  (hr) 

Duration  of  simulation 

Ramp  duration  (day) 

Duration  of  ramp 

|  (Sheet  1  of  3)  | 
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Table  5  (Continued)  jj 

Parameter 

Description 

Steering  Module  elapsed  time 

Cumulative  time  at  beginning  of  present 
simulation;  applied  for  multiple  simulations  with 
Steering  Module  j 

Time  to  write  output  for  hot-start  (hr) 

Time  when  hot  start  output  is  to  be  written. 

Use  a  value  of  0  if  no  hot-start  information  is  to 
be  saved, 

Grid  file  name 

Name  of  grid  file  (required) 

Initial  conditions  file  name 

Name  of  file  containing  initial  conditions.  If 
starting  the  simulation  from  quiescent 
conditions,  use  "default"  (without  the  quotes) 
instead  of  a  file  name. 

Tidal  constituents  file  name 

Name  of  file  containing  tidal  constituents2. 

Wind  input  file  name 

Name  of  file  containing  wind  speed  and 
direction  (required). 

Include  radiation  stresses 

Flag  for  inclusion  of  radiation  stress  forcing. 

Flag  settings:  0  =  no  radiation  stress  forcing,  1 
=  include  radiation  stress  forcing 

Wave  properties  file 

Name  of  a  file  containing  the  names  of  wave- 
properties  files  for  height,  period,  direction,  and 
breaking 

Radiation  stress  file 

Name  of  radiation  stress  file2.rad. 

Hot-start  output  file  name 

Name  of  hot  start  output  file2. 

Time-specification  file  for  vector  plot  output 

Name  of  file  containing  times  for  vector  plot 
(global  u,  v)  output2. 

Time-specification  file  for  global  elevation 
output 

Name  of  file  containing  times  for  global 
elevation  output2. 

Time-series  output  cell-specification  file 

Name  of  file  containing  cell  numbers  for  time- 
series  output  of  u ,  V,  TJ*. 

Flow  rate  output  time-series  cell-specification 
file 

Name  of  file  containing  cell  numbers  for  flow 
rate  output*. 

Time  between  output  file  writes  (s)  for  u,  v , 
time-series  file 

Time  should  be  a  multiple  of  the  simulation 
time-step 

Time  between  output  file  writes  (s)  for  flow-rate 
file 

Time  should  be  a  multiple  of  the  simulation 
time-step 

Time-series  output  file  for  u 

Name  of  file  to  contain  u  time  series2. 

Time-series  output  file  for  v 

Name  of  file  to  contain  vtime  series2. 

I  Time-series  output  file  for  ri 

Name  of  file  to  contain  r\  time  series2. 

I  Flow  rate  output  file  for  Qx 

Name  of  file  to  contain  time  series  of  Qx2. 

Flow  rate  output  file  for  Qy 

Name  of  file  to  contain  time  series  of  Qy2. 

Prefix  for  vector  output  file  name 

M2D  appends  H.m2v”  to  the  user-specified 
prefix  when  naming  the  vector  output  file. 

Prefix  for  global  elevation  output  file  name 

M2D  appends  ‘‘.m2s"  to  the  user-specified 
prefix  when  naming  the  global  elevation  file. 

(Sheet  2  of  3)  | 

Chapter  7  Model  Setup  and  File  Structure 


65 


|  Table  5  (Concluded) 

Parameter 

Description 

Prefix  for  global  bottom  change  output  file 
name 

M2D  appends  “.m2s”  to  the  user-specified  ? 

prefix  when  naming  the  global  bottom  change 
file. 

Prefix  for  transport  rate  output  file  name 

M2D  appends  \m2v"  to  the  user-specified 
prefix  when  naming  the  global  transport  rate 
file. 

HDRIVER  file  name 

Name  of  file  containing  water  surface  elevation 
forcing  information  (individual  time-series  files). 

QDRIVER  file  name 

Name  of  file  containing  flow  rate  forcing 
information. 

MHDRIVER  file  name 

Name  of  file  containing  water  surface  elevation 
forcing  information  (multiple  time-series  files). 

MVDRIVER  file  name 

Name  of  file  containing  velocity  forcing 
information  (multiple  time-series  files). 

|  (Sheet  3  of  3) 

1  1 .  Sediment  transport  in  M2D  is  under  development  and  is  not  presently  available  for  end  user. 

1  2.  Use  “none"  or  “NONE"  if  no  hot-start  output  for  this  variable  is  specified. 

Initial  conditions 

An  initial  conditions  file  provides  the  water  surface  elevation  and  velocity  at 
the  beginning  of  the  simulation  at  all  cells.  Each  line  in  the  initial  conditions  file 
contains  13  values.  The  eight  five  values  are  cell  number,  ambient  depth,  rj,  u,  v, 
dr\/dt ,  u  ,  and  v  .  Depth  and  water  level  are  given  in  m  and  velocity 
components  are  given  in  m/s.  The  9th  through  12th  values  are  the  cell  boundary 
type  indices  (Table  3),  and  the  13th  column  is  the  cell  activity  (IACTV) 
parameter.  M2D  writes  hot-start  files  in  the  correct  format  for  reading  as  initial 
conditions.  If  a  time-specific  hot  start  is  specified  within  the  SMS  model  control, 
the  hot-start  file  name  will  have  the  extension  “,m2i.”  If  the  automatic  recurring 
hot-start  capability  within  M2D  is  invoked,  the  hot-start  files  will  be  named 
“HOTSTART1  .M2I”  and  “HOTSTART2.M2I.”  Automatic  hot-starts  are 
invoked  by  setting  the  hot  start  time  interval  to  a  value,  in  hours,  greater  than 
zero. 


Water  level  forcing  data  files 

Time-series  boundary  forcing  for  M2D  can  be  specified  as  water  surface 
elevation.  Two  types  of  files  containing  water  surface  elevation  forcing 
information  can  be  applied.  One  type  contains  individual  time  series  and  the 
other  type  contains  multiple  time  series.  Both  the  individual  and  multiple  time 
series  forcing  can  be  applied  in  the  same  simulation.  This  capability  is 
convenient  for  situations  in  which  the  time  increment  is  not  equal  between 
different  sets  of  time  series.  This  capability  also  provides  flexibility  for  defining 
multiple  water  level  forcing  cell  strings  within  the  SMS  and  specifying  forcing 
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from  various  sources.  For  example,  a  simulation  may  require  that  one  or  more 
cell  strings  are  forced  by  data  from  a  water  level  gauge  and  use  the  individual 
forcing  file,  and  also  that  one  or  more  cell  strings  are  forced  by  water  levels 
calculated  by  ADCIRC  and  saved  in  a  multiple  time-series  file. 

M2D  recognizes  whether  time  series  of  water  level  are  specified  as  forcing 
by  identification  of  forcing  cells  in  the  grid  file.  If  time  series  water  level  driving 
cells  are  found,  M2D  opens  the  HDRIVER  and/or  MHDRTVER  files  (see 
Table  5).  The  first  line  of  the  HDRIVER  or  MHDRIVER  file  contains  two 
integer  values.  The  first  value  specifies  the  number  of  files  containing  water 
surface  elevation  forcing  time  series.  The  second  number  is  the  total  number  of 
cells  forced  by  water  surface  elevation  values  for  HDRIVER  files,  and  is  the 
maximum  number  of  cells  forced  by  water  surface  elevation  for 
MHDRIVER.DAT  files.  More  than  one  multiple  time  series  file  can  be  applied 
in  a  simulation.  The  maximum  number  of  cells  forced  by  water  surface  elevation 
is  the  greatest  number  of  cells  forced  for  all  files  listed  in  the  MHDRIVER.DAT 
file. 


The  second  line  contains  the  name  of  a  data  file  that  contains  the  forcing 
data.  The  third  line  of  the  HDRIVER  or  MHDRIVER.DAT  file  contains  the 
number  of  cells  that  are  driven  by  the  data  contained  in  the  file  listed  in  the 
second  line,  and  an  interpolation  parameter.  The  interpolation  parameter 
specifies  whether  or  not  the  forcing  data  are  interpolated  between  model  time- 
steps.  For  example,  water  level  forcing  data  may  be  available  every  hour,  but  the 
model  time-step  might  be  30  s.  If  the  interpolation  parameter  is  set  to  1,  values 
of  water  level  at  the  forcing  boundaries  are  interpolated  at  each  model  time-step. 
If  the  interpolation  parameter  is  set  to  0,  no  interpolation  takes  place.  Following 
the  first  and  second  lines  a  list  of  cell  numbers  that  are  forced  by  the  time  series 
data  given  in  the  forcing  data  file.  For  the  individual  time  series  forcing  files,  all 
cells  in  the  list  are  forced  by  the  same  single  time  series.  Cells  forced  by  water 
levels  contained  in  the  multiple  time  series  file  must  be  listed  in  the 
MHDRIVER.DAT  file  in  the  order  that  their  corresponding  time  series  appear  in 
the  forcing  data  file. 

If  more  than  one  forcing  data  file  is  applied  for  water  level  or  discharge, 
information  is  specified  exactly  as  previously  described  for  all  sets  of  forcing 
data  and  placed  in  the  HDRIVER  or  MHDRIVER  file  below  the  information  for 
the  first  file. 

If  individual  time  series  of  water  surface  elevation  is  specified  in  an  M2D 
project,  the  SMS  saves  the  HDRIVER  file  name  as  “hdriver_jprojectname.dat.” 

If  multiple  time-series  of  water  surface  elevation  is  specified  in  an  M2D  project, 
the  SMS  saves  the  MHDRIVER  file  name  as  “mhdriver_projectname.dat.” 

Files  containing  individual  time  series  water  level  forcing  data  (listed  in 
HDRIVER.DAT)  are  specified  to  have  two  values  on  each  line.  The  first  value  is 
the  time  stamp.  The  time  is  specified  in  hours  since  the  beginning  of  the 
simulation.  So,  at  t  =  0,  the  time  stamp  would  be  0.0  and  at  t  =  1  day,  the  time 
stamp  would  be  24.0.  The  second  value  is  water  surface  elevation  (m)  relative  to 
the  same  datum  as  the  grid  for  water  level  forcing  data,  or  flow  rate  (m3/s)  for 
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discharge  data.  Time  stamps  must  start  at  0.0  and  end  at  or  after  the  ending  time 
of  the  simulation. 


Files  containing  multiple  time-series  water  level  forcing  data  (listed  in 
MHDRIVER.DAT)  must  have  on  each  line  a  time  stamp  followed  by  a  water 
level  value  for  each  of  the  cells  listed  that  correspond  to  the  particular  forcing 
file.  Thus,  if  J  cells  are  to  be  forced  with  a  particular  multiple  time  series  file, 
then  J+l  columns  must  be  present  in  the  forcing  file.  Columns  of  water-level 
values  must  be  listed  in  the  same  order  as  the  cell  numbers  are  listed  in  the 
MHDRIVER.DAT  file.  The  time  is  specified  in  hours  since  the  beginning  of  the 
simulation.  So,  at  t  =  0,  the  time  stamp  would  be  0.0  and  at  t  =  1  day,  the  time 
stamp  would  be  24.0.  Water  surface  elevation  (m)  is  provided  relative  to  the 
same  datum  as  the  grid  for  water  level  forcing  data.  Time  stamps  must  start  at 
0.0  and  end  at  or  after  the  ending  time  of  the  simulation. 

The  SMS  contains  dialogs  in  which  time  series  of  water  surface  elevation 
and  flow  rate  can  be  prescribed  for  M2D.  If  these  dialogs  are  accessed  to  create 
the  time  series  files,  they  will  be  saved  with  the  extension  “.wl.” 


Velocity  forcing  data  files 

Forcing  by  velocity  information  can  be  applied  in  conjunction  with  the 
multiple  time  series  water  level  forcing.  The  velocity  format  is  also  a  multiple 
time  series.  Velocity  time  series  cannot  be  specified  without  water  level  forcing 
at  the  same  cells. 

M2D  recognizes  whether  time  series  of  combined  water  level  and  velocity 
values  are  applied  as  forcing  by  identification  of  forcing  cells  in  the  grid  file.  If 
time  series  combined  water  level  and  velocity  driving  cells  are  found,  M2D 
opens  the  MHDRIVER  and  MVDRIVER  files  (see  Table  5).  The  file  format  for 
the  MVDRIVER  file  is  identical  to  that  of  the  MHDRIVER  file  described  in  the 
previous  section  of  this  chapter.  SMS  saves  the  MVDRIVER  file  as 
“mvdriver_projectname.dat.” 

Files  containing  multiple  time  series  velocity  forcing  data  (listed  in 
MVDRIVER.DAT)  must  have  on  each  line  a  time  stamp  followed  by  four 
velocity  values  for  each  of  the  cells  listed  that  correspond  to  the  particular 
forcing  file.  Velocities  written  for  each  cell  are  those  on  the  cell  faces  and  are 
written  in  the  following  order:  W/e/„  urighh  vhoUom,  vtop  where  the  subscripts  left, 
right,  bottom,  and  top  denote  the  cell  faces  in  the  grid  coordinate  system.  Thus, 
if  J  cells  are  to  be  forced  with  a  particular  multiple  time  series  file,  then  4*  J+l 
columns  must  be  present  in  the  forcing  file.  Columns  of  sets  of  velocity  values 
must  be  listed  in  the  same  order  as  the  cell  numbers  are  listed  in  the 
MVDRIVER.DAT  file.  The  time  is  specified  in  hours  since  the  beginning  of  the 
simulation.  So,  at  t  =  0,  the  time  stamp  would  be  0.0  and  at  t  =  1  day,  the  time 
stamp  would  be  24.0.  Time  stamps  must  start  at  0.0  and  end  at  or  after  the 
ending  time  of  the  simulation. 
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The  SMS  contains  a  dialog  in  which  time  series  of  combined  water-surface 
elevation  and  velocity  can  be  prescribed  for  M2D  in  which  the  boundary  values 
are  obtained  from  the  solution  of  a  larger-domain  model.  SMS  automatically 
maps  the  solution  to  the  M2D  cells. 


Flow  rate  forcing  data  files 

Flow  rate  is  forced  by  files  containing  individual  time  series  information. 
M2D  recognizes  whether  time  series  flow  rate  values  are  applied  as  forcing  by 
identification  of  forcing  cells  in  the  grid  file.  If  time  series  flow  rate  driving  cells 
are  found,  M2D  opens  the  QDRIVER  file  (see  Table  5).  The  first  line  of  the 
QDRIVER  file  contains  two  integer  values.  The  first  value  specifies  the  number 
of  files  containing  flow  rate  forcing  time  series.  The  second  number  is  the  total 
number  of  cells  forced  by  flow  rate. 

The  second  line  contains  the  name  of  a  data  file  that  contains  the  forcing 
data.  The  third  line  of  the  QDRIVER  file  contains  the  number  of  cells  that  are 
driven  by  the  data  contained  in  the  file  listed  in  the  second  line,  and  an 
interpolation  parameter.  The  interpolation  parameter  specifies  whether  or  not  the 
forcing  data  are  interpolated  between  model  time-steps.  For  example,  flow  rate 
forcing  data  may  be  available  every  hour,  but  the  model  time-step  might  be  30  s. 
If  the  interpolation  parameter  is  set  to  1,  values  of  flow  rate  at  the  forcing 
boundaries  are  interpolated  at  each  model  time-step.  If  the  interpolation 
parameter  is  set  to  0,  no  interpolation  takes  place.  Following  the  first  and  second 
lines  of  the  QDRIVER  file  is  a  list  of  cell  numbers  that  are  forced  by  the  time 
series  data  given  in  the  forcing  data  file. 

If  more  than  one  forcing  data  file  is  applied  for  flow  rate,  information  is 
specified  exactly  as  previously  described  for  all  sets  of  forcing  data  and  placed  in 
the  QDRIVER  file  below  the  information  for  the  first  file. 

If  time  series  of  water  surface  elevation  is  specified  in  an  M2D  project,  the 
SMS  saves  the  QDRIVER  file  name  as  “qdriver_projectname.dat.” 

Files  containing  flow  rate  forcing  data  are  specified  to  have  two  values  on 
each  line.  The  first  value  is  the  time  stamp.  The  time  is  specified  in  hours  since 
the  beginning  of  the  simulation.  So,  at  t  =  0,  the  time  stamp  would  be  0.0  and  at 
t  =  1  day,  the  time  stamp  would  be  24.0.  Time  stamps  must  start  at  0.0  and  end 
at  or  after  the  ending  time  of  the  simulation.  The  second  value  is  flow  rate  given 
in  m3/s.  This  flow  rate  is  specified  at  every  cell  designated  as  forced  by  the  input 
series  in  the  QDRIVER  file.  Thus,  if  three  cells  were  specified  as  flow  rate 
forcing  cells  and  the  value  of  the  flow  rate  was  9  m3/s,  then  each  of  the  three  cells 
would  have  9  m3/s  flowing  through  it.  The  flow  rate  is  not  distributed  among  the 
three  cells. 

The  SMS  contains  a  dialog  in  which  time  series  of  flow  rate  can  be 
prescribed  for  M2D.  If  this  dialog  is  accessed  to  create  the  time  series  files,  they 
will  be  saved  with  the  extension  “.q.” 


Chapter  7  Model  Setup  and  File  Structure 


69 


Wind  speed  and  direction 


Wind  speed  and  direction  are  given  in  the  user-specified  wind  file  listed  in 
m2d.m2c.  The  wind-forcing  file  contains  three  values  on  each  line.  The  first 
value  is  the  time  stamp  in  hours  since  the  beginning  of  the  simulation.  The 
second  value  is  the  wind  speed  in  m/s  and  the  third  value  is  direction  in  deg.  The 
convention  for  the  input  wind  direction  is  0  deg  indicates  wind  blowing  from  the 
north,  and  90  deg  indicates  wind  blowing  from  the  east.  Wind  speed  must  be 
positive.  Conversion  to  the  wind-direction  convention  given  for  Equations  2  and 
3  is  conducted  internally  within  M2D. 

The  SMS  contains  a  dialog  in  which  time  series  of  wind  speed  and  direction 
can  be  prescribed  for  M2D.  If  this  dialog  is  accessed  to  create  the  time  series 
file,  it  will  be  saved  with  the  extension  “.m2w.” 


Tidal  constituents 

The  tidal-constituent  forcing  file  contains  nine  lines.  The  first  line  is  a 
header  that  can  identify  the  source  of  the  tidal-constituent  information.  The 
header  line  is  ignored  by  M2D.  Each  of  the  remaining  lines  contain  the  local 
amplitude  (m)  and  phase  (deg)  of  the  water  level  for  a  specific  tidal  constituent. 
The  constituents  specified  on  lines  2  through  9  are  (in  order  of  appearance):  M2, 
N2,  S2,  K2,  Kj,  Oi,  M4,  and  M6.  If  specific  constituents  are  not  to  be  specified  as 
forcing,  then  their  amplitude  values  must  be  set  to  zero. 


Wave  stresses 

Wave  stresses  are  given  in  the  user-specified  radiation-stress  file  listed  in 
m2d.m2c.  The  radiation-stress  file  consists  of  sets  of  wave  stresses  prescribed  at 
specific  times.  The  first  line  in  the  file  contains  the  text  “TIME:”  and  is  followed 
by  the  time  in  hours  since  the  beginning  of  the  simulation.  Lines  2  through 
NCELLS  +  1  contain  three  values.  The  first  value  is  the  cell  identification 
number,  the  second  and  third  values  are  the  x  and  y-components  of  the  wave 
stress,  respectively.  Wave  stresses  must  be  given  in  order  of  ascending  cell 
identification  numbers.  Sets  of  information  that  include  the  time-step  and  wave 
stresses  for  each  cell  are  included  in  the  file  for  each  time-step  that  wave  stresses 
are  available.  Because  M2D  will  conduct  its  calculations  at  a  different  time 
interval  than  the  wave  stress  time  interval,  the  stresses  are  linearly  interpolated 
within  M2D  over  time.  If  the  last  time  stamp  in  the  wave  stress  file  specifies  a 
time  before  the  end  of  the  M2D  simulation,  M2D  will  apply  values  of  zero  for 
the  radiation  stresses  after  the  time  of  the  last  available  wave  information  (no 
interpolation  to  zero  is  conducted). 

If  the  Steering  Module  is  invoked  to  couple  M2D  with  STWAVE,  SMS  will 
write  files  containing  wave  stresses  that  have  been  mapped  from  those  calculated 
by  the  wave  model.  SMS  gives  the  extension  “.rad”  to  the  wave  stress  file.  The 
same  file  extension  is  also  given  to  radiation  stress  files  for  STWAVE.  M2D 


70 


Chapter  7  Model  Setup  and  File  Structure 


files  can  be  distinguished  from  the  STWAVE  files  by  the  prefix.  M2D  wave 
stress  files  contain  the  text  “m2steer”  and  the  STWAVE  files  contain  “s2steer.” 


Selected  cell  output  specification  file 

User-specified  observation  cells  can  be  selected  for  time  series  output  of 
variables  or  terms  in  the  governing  equations.  A  listing  of  these  cells  is  provided 
in  a  cell  output  specification  file.  The  file  consists  of  a  list  of  cell  identification 
numbers  with  one  number  per  line.  If  observation  cells  are  selected  within  the 
SMS  and  saved  as  part  of  an  M2D  project,  SMS  gives  the  cell  listing  file  the 
extension  of  “.ts.” 


Global  output  time  specification  files 

Global  water  surface  elevation  and  velocity  are  written  to  files  at  times 
specified  in  the  global  output  time-specification  files.  These  files  consist  of  a  list 
of  times,  in  hours  since  the  beginning  of  the  simulation,  at  which  global  output  is 
to  be  written.  Each  line  in  these  files  consists  of  one  time  value.  Separate  global 
output  time-specification  files  are  required  for  water  surface  elevation  and 
velocity,  providing  the  option  to  save  only  one  global  file. 

Times  listed  in  the  global  output  time-specification  files  can  be  at  constant  or 
varying  time  intervals.  Requirements  for  the  times  listed  in  the  file  are  that  they 
are  sequential,  start  at  values  of  zero  or  greater,  and  values  are  not  repeated. 

If  global  output  times  are  specified  within  the  SMS,  a  series  of  equal- 
increment  output  times  can  be  generated.  In  addition,  individual  times  can  also 
be  specified.  If  both  water  surface  elevation  and  velocity  global  files  are  to  be 
written,  the  output  times  from  one  of  these  variables  can  be  written  to  the  other 
so  that  the  global  output  will  take  place  at  the  same  times.  SMS  writes  the  global 
output  time-specification  files  with  an  extension  of  “.m2t.” 


Output  Files 

Two  types  of  output  files  can  be  specified  for  M2D.  These  file  types  are 
time  series  of  a  variable  at  station  locations  and  global  variable  files. 

Descriptions  of  these  file  types  are  given  here.  For  both  types  of  output  files, 
each  variable  is  reported  from  its  computational  location  in  the  model.  Thus, 
water  surface  elevation  is  reported  from  the  cell  center,  the  x-component  of 
velocity  is  reported  from  the  left  cell  face  center,  and  the  y-component  of  velocity 
is  reported  from  the  bottom  cell  face  center. 
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Time  series  at  station  locations 


Time  series  output  files  for  specific  station  locations  contain  a  header  line 
followed  by  the  calculated  time  series  values.  The  header  specifies  the  cell 
numbers  (where  output  is  taken)  above  columns  of  output.  Cell  numbers  in  the 
header  are  written  as  “C#”  where  #  denotes  the  cell  number.  The  “C”  is  placed 
in  the  header  to  distinguish  the  cell  number  from  data  in  plotting  packages 
(software  will  read  the  information  in  as  a  character  string).  Lines  following  the 
header  contain  a  time  stamp  (fractional  days)  and  values  of  the  variable. 

Water  surface  elevation  and  the  two  components  of  velocity  are  each  written 
to  separate  files  for  a  total  of  three  possible  station  output  files.  The  user  can 
specify  any  combination  of  time  series  station  output  files  to  be  written. 


Global  output  time  specification  files 

Global  files  can  be  created  for  water  surface  elevation,  velocity,  and  depth 
change.  File  formats  consist  of  sets  of  global  variable  values  output  at  times 
specified  by  the  user.  Each  set  of  information  in  the  file  contains  a  line  with  the 
time  stamp,  followed  by  lines  containing  the  x,y  position  of  each  cell  followed  by 
the  value  of  the  variable,  such  as  rj.  For  velocity,  these  lines  contain  u  and  v. 
Global  information  is  saved  for  each  cell  in  the  grid  and  written  in  ascending 
order  of  cell  identification  number.  File  extensions  of  .m2s  are  assigned  to  scalar 
fields  and  .m2v  to  vector  fields. 

Units  for  time  series  and  global  files  are  standard  metric.  Water  surface 
elevation  is  given  in  m  and  velocity  is  given  in  m/s.  Time  stamps  are  given  in 
hours  since  the  beginning  of  the  simulation. 
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Appendix  A 

Example  Input  and  Output 
Files 


This  appendix  provides  example  input  and  output  files  for  M2D.  Sample 
files  were  selected  from  various  applications  to  illustrate  file  formats.  Input  files 
are  shown  first,  followed  by  output  files. 

An  example  grid  file  is  shown  in  Figure  A1  for  a  19-km-long  frictionless 
channel.  The  channel  is  19  cells  long,  1  cell  wide,  and  1  m  deep.  Cells  have 
dimensions  of  1,000  m  on  each  side.  Cell-center  coordinates,  x-dist  and  y-dist, 
are  given  in  meters  from  the  grid  origin. 
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Figure  A1 .  Example  grid  file  for  channel 


An  example  m2d.m2c  file  is  shown  in  Figure  A2.  In  this  example,  a  100-hr 
simulation  is  specified  with  a  0.5-s  time-step.  The  automatic  recurring  hot-start 
capability  is  invoked  with  hot-start  files  written  every  24  hr.  Advective  terms  in 
the  momentum  equations  are  included  in  the  computations.  Wetting  and  drying 
is  allowed  to  occur  and  cells  will  dry  at  a  water  depth  of  0.08  m.  Wind  speed  and 
direction  is  specified  in  the  file  “periodic.wnd.”  Global  velocity  and  water 
surface  elevation  are  to  be  written  at  times  specified  in  the  “ideal4_v.m2t”  and 
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“ideal4_e.m2t”  files,  respectively.  Time  series  output  is  to  be  saved  every  600  s 
for  cells  listed  in  the  file  “ideal4.ts”  and  the  variables  to  be  saved  are  w,  v,  and  rj. 
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An  example  time-specification  file  for  either  global  vector  or  scalar 
(elevation)  output  is  shown  in  Figure  A3.  A  list  of  specific  times,  in  hours,  with 
one  time  value  per  line,  are  provided  at  which  M2D  will  write  out  the  global 
output  file. 


Version  2.00 

10.0 

ANEMOMETER  HEIGHT  (M) 

0.0012 

RHO  ATM/RHO  WATER 

10.27 

ANGLE  BETWEEN  TRUE  NORTH  AND  Y-AXIS  OF  GRID 

567607.0602 

GRID  ORIGIN  (M),  (X-COORDINATE) 

77050.4225 

GRID  ORIGIN  (M),  (Y-COORDINATE) 

1.0000 

DELTA  T  (SEC) 

0.000 

AUTOMATIC  RECURRING  HOT  START  INTERVAL  (HR) 

1 

INCLUDE  ADVECTIVE  TERMS:  0  =  NO,  1  =  YES 

0 

INCLUDE  MIXING  TERMS:  0  =  NO,  1  =  YES 

1 

ALLOW  WETTING  AND  DRYING:  0  =  NO,  1  =  YES 

0.05 

DEPTH  (M)  TO  BEGIN  DRYING  CELLS 

0 

CALCULATE  SEDIMENT  TRANSPORT:  0  =  NO,  1  =  YES 

0.00 

DELTA  T  FOR  SEDIMENT  TRANSPORT  (SEC) 

02230 

STARTING  JULIAN  DAY  (YYDDD  OR  DDD) 

19 

START  TIME  (HOUR) 

72.000 

REALIZATION  TIME  (HOUR) 

0.500 

RAMP  DURATION  (DAY) 

0.000 

STEERING  MODULE  (MULTIPLE  SIMULATION)  ELAPSED  TIME  (HOUR) 

75.000 

TIME  TO  WRITE  OUTPUT  FOR  HOT  START  (HR) 

OceanCity.m2g 

GRID  INPUT  FILE  NAME 

default 

INITIAL  CONDITIONS  FILE  NAME 

none 

TIDAL  CONSTITUENT  INPUT  FILE 

none 

WIND  INPUT  FILE 

1 

INCLUDE  RADIATION  STRESSES:  0  =  NO,  1  =  YES 

Ocean  City,  mwv 

WAVE  DATA  FILE 

1m2steer.rad 

RADIATION  STRESS  INPUT  FILE  (WRITTEN  BY  STWAVE) 

1m2steer.m2i 

HOT  START  OUTPUT  FILE 

OC  V.m2t 

TIME  SPECIFICATION  FILE  FOR  VECTOR  PLOT  OUTPUT 

OC_E.m2t 

TIME  SPECIFICATION  FILE  FOR  GLOBAL  ELEVATION  OUTPUT 

none 

TIME-SERIES  INPUT  FILE 

none 

FLOW  RATE  TIME-SERIES  INPUT  FILE 

0 

TIME  BETWEEN  OUTPUT  FILE  WRITES  (SEC)  FOR  TIME-SERIES  FILE 

0 

TIME  BETWEEN  OUTPUT  FILE  WRITES  (SEC)  FOR  FLOW  RATE  FILE 

none 

TIME-SERIES  OUTPUT  FILE  FOR  U 

none 

TIME-SERIES  OUTPUT  FILE  FOR  V 

none 

TIME-SERIES  OUTPUT  FILE  FOR  ETA 

none 

FLOW  RATE  OUTPUT  FILE  FOR  X-DIRECTION 

none 

FLOW  RATE  OUTPUT  FILE  FOR  Y-DIRECTION 

TideWave 

PREFIX  FOR  VECTOR  OUTPUT  FILE  NAME 

TideWave 

PREFIX  FOR  GLOBAL  ELEVATION  OUTPUT  FILE  NAME 

none 

PREFIX  FOR  GLOBAL  BOTTOM  CHANGE  FILE  NAME 

none 

PREFIX  FOR  GLOBAL  SEDIMENT  TRANSPORT  RATE  FILE  NAME 

none 

HDRIVER.DAT  FILE 

none 

QDRIVER.DAT  FILE 

mhdriver_OC.dat 

MHDRIVER.DAT  FILE 

mvdriver_OC.dat 

MVDRIVER.DAT  FILE 

Figure  A2.  Example  m2d.m2c  file 


Appendix  A  Example  Input  and  Output  Files 


0.00 

1.00 

2.00 

3.00 

4.00 

5.00 

6.00 

7.00 

8.00 

9.00 

10.00 

11.00 


Figure  A3.  Example  time-specification  file  for  global  output 


An  example  hdriver.dat  file  is  shown  in  Figure  A4.  Two  water  level  forcing 
files  will  be  read  and  the  total  number  of  water  surface  elevation  forcing  cells  is 
10.  Files  “Gaugel.wl”  and  “Gauge2.wl”  contain  water  level  forcing  data.  Data 
from  Gaugel.wl  is  prescribed  at  four  cells  (cell  numbers  1,  2,  3, 4)  and  the  water 
level  is  to  be  interpolated  between  model  time-steps.  Data  from  Gauge2.wl  is 
applied  at  six  cells  (cell  numbers  64,  65,  66,  67,  68,  and  69)  with  interpolation 
between  model  time-steps.  Qdriver.dat  files  have  identical  format,  so  a  separate 
example  is  not  given. 


2  10 

Gaugel.wl 
4  1 
1 
2 

3 

4 

Gauge2 .wl 
6  1 

64 

65 

66 

67 

68 
69 


Figure  A4.  Example  hdriver.dat  file 


An  example  of  a  time  series  water  level  forcing  file  is  shown  in  Figure  A5. 
Files  “Gauge l.wl”  and  “Gauge2.wr  shown  in  Figure  A4  are  in  this  format.  The 
first  column  contains  time  stamps  (hours)  and  the  second  column  provides  water 
level  (m).  Flow  rate  forcing  files  have  the  same  format  as  shown  in  Figure  A5. 
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0 

-0.0455 

0.9912 

0.0319 

1.992 

0.1373 

2.9928 

0.2738 

3.9912 

0.3948 

4.992 

0.4652 

5.9928 

0.4515 

6.9912 

0.3759 

7.992 

0.2864 

8.9928 

0.1967 

9.9912 

0.1102 

10.992 

0.0302 

11.9928 

-0.0423 

12.9912 

-0.1053 

13.992 

-0.1573 

14.9928 

-0.1991 

15.9912 

-0.2295 

16.992 

-0.2483 

17.9928 

-0.2584 

18.9912 

-0.2647 

19.992 

-0.2727 

20.9928 

-0.2858 

21.9912 

-0.3036 

22.992 

-0.3236 

23.9928 

-0.3428 

24.9912 

-0.2356 

Figure  A5.  Example  individual  time  series  water  level  forcing  file 


An  example  wind  forcing  file  is  shown  in  Figure  A6.  The  duration  of  the 
wind  forcing  is  22  hr  and  oscillates  between  90  (blowing  from  the  east)  and 
270  deg  (blowing  from  the  west).  Wind  speed  ranges  from  0  to  8.6  m/s. 


"TO - 

—TO - 

- 570 - 

1.0 

1.0 

90.0 

2.0 

2.0 

90.0 

3.0 

2.5 

90.0 

4.0 

3.0 

90.0 

5.0 

3.5 

270.0 

6.0 

4.0 

270.0 

7.0 

4.5 

270.0 

8.0 

5.0 

270.0 

9.0 

5.5 

270.0 

10.0 

5.8 

270.0 

11.0 

6.0 

270.0 

12.0 

6.5 

270.0 

13.0 

6.8 

270.0 

14.0 

7.0 

270.0 

15.0 

7.0 

270.0 

16.0 

5.0 

270.0 

17.0 

2.5 

270.0 

18.0 

0.0 

90.0 

19.0 

2.5 

90.0 

20.0 

5.0 

90.0 

21.0 

7.0 

90.0 

22.0 

8.6 

90.0 

Figure  A6.  Example  time  series  wind  forcing  file 
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An  example  tidal-constituents  forcing  file  is  shown  in  Figure  A7.  The 
constituent  identifiers  (e.g.  M2”)  are  not  required  in  the  file,  but  remind  the 

user  of  the  order  of  the  constituents. 


US  Naval  Academy,  Annapolis,  MD  Tidal  Constituents 


0 

1344 

147 

20 

M2 

0 

0226 

175 

00 

S2 

0 

0262 

126 

00 

N2 

0 

0061 

174 

5 

K2 

0. 

.0579 

283. 

.30 

Kl 

0. 

.0500 

294. 

.10 

01 

0. 

.0037 

130. 

.60 

M4 

0. 

.0 

0. 

.0 

M6 

Figure  A7.  Example  tidal-constituents  forcing  file 


An  example  portion  of  an  initial  conditions  file  is  shown  in  Figure  A8.  In 
this  example,  water  levels  are  set  to  non-zero  values,  the  u-  and  v-components  of 
velocity  are  zero,  values  of  cr|  /  dt  are  non-zero,  u 1  has  zero  and  non-zero 

values,  and  v'  values  are  zero.  Cell  boundary  types  and  activity  codes  are  also 
written. 


1 

0.67100000 

0.24883273 

0.000000 

0.000000 

0.08816975 

0.000000 

0.000000 

0 

7 

7 

4 

6 

2 

1.36300004 

0.21381602 

0.000000 

0.000000 

0.05334590 

0.007975 

0.000000 

0 

7 

7 

7 

6 

3 

2.05500007 

0.17855626 

0.000000 

0.000000 

0.01846295 

0.007990 

0.000000 

0 

7 

7 

7 

6 

4 

2.73600006 

0.15381116 

0.000000 

0.000000 

-0.00601869 

0.004049 

0.000000 

0 

7 

7 

7 

6 

5 

3.40400004 

0.14469834 

0.000000 

0.000000 

-0.01528861 

-0.000789 

0.000000 

0 

7 

7 

7 

6 

6 

4.03200006 

0.14424038 

0.000000 

0.000000 

-0.01594494 

-0.003016 

0.000000 

0 

7 

7 

7 

6 

7 

4.65199995 

0.14831893 

0.000000 

0.000000 

-0.01212788 

-0.004057 

0.000000 

0 

7 

7 

7 

6 

8 

5.22100019 

0.15106325 

0.000000 

0.000000 

-0.00958566 

-0.003458 

0.000000 

0 

7 

7 

7 

6 

9 

5.77400017 

0.15291372 

0.000000 

0.000000 

-0.00784420 

-0.002194 

0.000000 

0 

7 

7 

7 

6 

10 

6.15199995 

0.15405130 

0.000000 

0.000000 

-0.00672851 

-0.000903 

0.000000 

0 

7 

7 

7 

6 

11 

6.32700014 

0.15448837 

0.000000 

0.000000 

-0.00623937 

0.000471 

0.000000 

0 

7 

7 

7 

6 

12 

6.49300003 

0.15473600 

0.000000 

0.000000 

-0.00594525 

0.001190 

0.000000 

0 

7 

7 

7 

6 

13 

6.67199993 

0.15503238 

0.000000 

0.000000 

-0.00564533 

0.001777 

0.000000 

0 

7 

7 

7 

6 

14 

6.85799980 

0.15532908 

0.000000 

0.000000 

-0.00537130 

0.002218 

0.000000 

0 

7 

7 

7 

6 

15 

7.03599977 

0.15554351 

0.000000 

0.000000 

-0.00514706 

0.002687 

0.000000 

0 

7 

7 

7 

6 

16 

7.20100021 

0.15569794 

0.000000 

0.000000 

-0.00493140 

0.002957 

0.000000 

0 

7 

7 

7 

6 

17 

7.37400007 

0.15586072 

0.000000 

0.000000 

-0.00466013 

0.002974 

0.000000 

0 

7 

7 

7 

6 

18 

7.55999994 

0.15609157 

0.000000 

0.000000 

-0.00429774 

0.002568 

0.000000 

0 

7 

7 

7 

6 

19 

7.84700012 

0.15658177 

0.000000 

0.000000 

-0.00365273 

0.001598 

0.000000 

0 

7 

7 

7 

6 

20 

8.19799995 

0.15755470 

0.000000 

0.000000 

-0.00278718 

-0.001382 

0.000000 

0 

7 

7 

7 

6 

Figure  A8.  Example  portion  of  an  initial  conditions  file 


An  example  portion  of  a  radiation-stress  input  file  is  shown  in  Figure  A9. 
The  format  of  this  file  requires  that  the  radiation-stress  gradients  have  been 
previously  mapped  to  the  M2D  grid  (SMS  conducts  this  mapping  automatically 
in  the  Steering  Module).  The  x  andy  components  are  oriented  relative  to  the 
M2D  axes.  The  first  line  in  the  file  provides  the  time  stamp.  Second  and  further 
lines  up  to  NCELLS  +  1  provide  the  cell  number,  x  component  of  the  radiation- 
stress  gradient,  and  y  component  of  the  radiation-stress  gradient.  Sets  of 
radiation-stress  gradients  for  successive  times  are  included  in  the  same  input  file. 
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TIME: 

0.000000 

1 

8.473935E-005  -1. 347822E-004 

2 

8.474045E-005  -1. 349220E-004 

3 

8.474155E-005  -1. 350617E-004 

4 

8.474265E-005  -1. 352014E-004 

5 

8.474375E-005  -1. 353411E-004 

6 

8.474485E-005  -1. 354808E-004 

7 

8.474595E-005  -1. 356205E-004 

8 

8.474705E-005  -1. 357603E-004 

9 

8.474815E-005  -1. 359000E-004 

10 

8.474925E-005  -1. 360397E-004 

11 

8.475035E-005  -1. 361794E-004 

12 

8.475145E-005  -1. 363191E-004 

13 

8.475255E-005  -1. 364588E-004 

14 

8.475365E-005  -1. 365986E-004 

15 

8.475475E-005  -1. 367383E-004 

16 

8.475585E-005  -1. 368780E-004 

17 

8.475695E-005  -1. 370177E-004 

18 

8.475804E-005  -1. 371574E-004 

19 

8.475915E-005  -1. 372971E-004 

20 

8.476025E-005  -1. 374368E-004 

21 

8.476135E-005  -1. 375766E-004 

22 

8.476245E-005  -1. 377163E-004 

23 

8.476355E-005  -1. 378560E-004 

24 

8.476465E-005  -1. 379957E-004 

25 

8.476575E-005  -1. 381354E-004 

26 

8.476685E-005  -1. 382751E-004 

27 

8.476795E-005  -1. 384148E-004 

28 

8.476905E-005  -1. 385546E-004 

Figure  A9.  Example  portion  of  radiation  stress  input  file 


An  example  portion  of  a  time  series  numerical  station  output  file  is  shown  in 
Figure  A 10,  in  which  five  cells  were  selected  for  output.  The  cell  numbers  for 
the  five  cells  are  1,  2,  3, 4,  and  5.  Time  is  elapsed  time  in  days  since  the 
beginning  of  the  simulation. 

Example  portions  of  global  elevation  and  velocity  files  are  shown  in 
Figures  All  and  A 12,  respectively.  In  these  examples,  the  time  of  the  output  is 
5.6  hr  after  the  beginning  of  the  simulation.  Coordinates  of  cell  positions  are 
given  in  the  first  two  columns  in  order  of  ascending  cell  number.  Cell 
coordinates  are  those  specified  in  the  grid  file  in  the  x-dist  and  y-dist  columns 
(grid  not  shown  for  these  global  output  examples).  Water  level  is  given  in  meters 
(third  column),  following  cell  coordinates;  x-  and  y-components  of  velocity  are 
given  in  meters  per  second  (third  and  fourth  columns,  respectively).  If  multiple 
times  of  global  values  are  written,  they  are  successively  appended  at  the  end  of 
the  file  with  no  lines  between  snapshots. 
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TIME  cl 

0.0000  -0.1900 
0.0000  -0.1873 
0.0003  -0.1821 
0.0007  -0.1753 
0.0010  -0.1675 
0.0014  -0.1594 
0.0017  -0.1515 
0.0021  -0.1439 
0.0024  -0.1366 
0.0028  -0.1295 
0.0031  -0.1224 
0.0035  -0.1150 
0.0038  -0.1076 
0.0042  -0.1000 
0.0045  -0.0924 
0.0049  -0.0849 
0.0052  -0.0776 
0.0056  -0.0703 
0.0059  -0.0630 
0.0063  -0.0556 
0.0066  -0.0482 


c2 

c3 

-0. 

,1700 

-0. 

.1500 

-0. 

,1700 

-0. 

.  1500 

-0. 

,1696 

-0. 

.1500 

-0. 

.1683 

-0. 

.1499 

-0. 

,1654 

-0. 

.1497 

-0. 

.1606 

-0, 

.1488 

-0. 

.1541 

-0. 

.1470 

-0. 

,1462 

-0. 

.1438 

-0. 

.  1377 

-0. 

.1389 

-0. 

.1292 

-0. 

.1324 

-0. 

.1212 

-0, 

.1245 

-0. 

,1138 

-0, 

.1158 

-0. 

.1069 

-0, 

.1071 

-0. 

.1001 

-0, 

.0988 

-0. 

.0931 

-0, 

.0912 

-0. 

.0857 

-0, 

.0842 

-0. 

.0781 

-0, 

.0775 

-0. 

.0703 

-0, 

.0708 

-0. 

.0626 

-0. 

.0637 

-0. 

.0550 

-0, 

.0562 

-0, 

.0478 

-0, 

.0483 

c4 

c5 

-0. 

,1300 

-0. 

.1100 

-0. 

,1300 

-0. 

.1100 

-0. 

,1300 

-0. 

.1100 

-0. 

,1300 

-0, 

.1100 

-0. 

,1300 

-0. 

.1100 

-0. 

.1299 

-0. 

.1100 

-0. 

.1298 

-0, 

.1100 

-0. 

.1292 

-0, 

.1100 

-0. 

,1280 

-0, 

.1098 

-0. 

.1259 

-0, 

.1095 

-0. 

.1223 

-0, 

.1087 

-0. 

,1172 

-0, 

.1072 

-0. 

.1105 

-0, 

.1047 

-0. 

.1026 

-0, 

.1008 

-0. 

.0939 

-0 

.0954 

-0. 

.0850 

-0 

.0886 

-0. 

.0765 

-0, 

.0806 

-0. 

.0688 

-0, 

.0718 

-0. 

.0617 

-0, 

.0628 

-0. 

.0550 

-0, 

.0543 

-0, 

.0484 

-0, 

.0464 

Figure  A10.  Example  time  series  numerical  station  output  file 


TIME:  5.60000 

3771.25000 

3833.75000 

3896.25000 

3958.75000 

4021.25000 

4083.75000 

4146.25000 

4208.75000 

4271.25000 

4333.75000 

4396.25000 

4458.75000 

4521.25000 

4583.75000 

4646.25000 

4708.75000 

4771.25000 

4833.75000 

4896.25000 

4958.75000 

5021.25000 

5083.75000 

5146.25000 

5208.75000 

5271.25000 

5333.75000 

5396.25000 

5458.75000 

5521.25000 

5583.75000 

5646.25000 

5708.75000 
5764.35010 


2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

2786.41040 

0.1500 

Figure  A1 1 .  Example  global  elevation  output  file 
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TIME:  5.60000 

3771.25000 

2786.41040 

0.0000 

-0.0104 

3833.75000 

2786.41040 

0.0000 

-0.0104 

3896.25000 

2786.41040 

0.0000 

-0.0095 

3958.75000 

2786.41040 

0.0000 

-0.0118 

4021.25000 

2786.41040 

0.0000 

-0.0130 

4083.75000 

2786.41040 

0.0000 

-0.0140 

4146.25000 

2786.41040 

0.0000 

-0.0145 

4208.75000 

2786.41040 

0.0000 

-0.0151 

4271.25000 

2786.41040 

0.0000 

.  -0.0155 

4333.75000 

2786.41040 

0.0000 

-0.0159 

4396.25000 

2786.41040 

0.0000 

-0.0164 

4458.75000 

2786.41040 

0.0000 

-0.0168 

4521.25000 

2786.41040 

0.0000 

-0.0172 

4583.75000 

2786.41040 

0.0000 

-0.0176 

4646.25000 

2786.41040 

0.0000 

-0.0181 

4708.75000 

2786.41040 

0.0000 

-0.0186 

4771.25000 

2786.41040 

0.0000 

-0.0191 

4833.75000 

2786.41040 

0.0000 

-0.0196 

4896.25000 

2786.41040 

0.0000 

-0.0201 

4958.75000 

2786.41040 

0.0000 

-0.0208 

5021.25000 

2786.41040 

0.0000 

-0.0214 

5083.75000 

2786.41040 

0.0000 

-0.0222 

5146.25000 

2786.41040 

0.0000 

-0.0231 

5208.75000 

2786.41040 

0.0000 

-0.0241 

5271.25000 

2786.41040 

0.0000 

-0.0252 

5333.75000 

2786.41040 

0.0000 

-0.0266 

5396.25000 

2786.41040 

0.0000 

-0.0282 

5458.75000 

2786.41040 

0.0000 

-0.0302 

5521.25000 

2786.41040 

0.0000 

-0.0326 

5583.75000 

2786.41040 

0.0000 

-0.0356 

5646.25000 

2786.41040 

0.0000 

-0.0394 

5708.75000 

2786.41040 

0.0000 

-0.0441 

5764.35010 

2786.41040 

0.0000 

-0.0493 

Figure  A12.  Example  global  velocity  output  file 


A8 


Appendix  A  Example  Input  and  Output  Files 


Appendix  B 
M2D  Citations 


This  appendix  provides  a  listing  of  publications  known  to  the  authors  to  date 
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Appendix  C 
Slosh  Tests 


This  appendix  describes  the  performance  of  M2D  for  slosh  tests.  This  set  of 
numerical  integrity  tests  evaluates  mass  conservation  and  numerical  damping 
properties  of  the  model.  Finite-difference  approximations  to  the  full  equations  of 
motion  truncate  terms  to  some  order  in  a  manner  that  depends  on  the  numerical 
solution  method.  Tmncation  of  terms  is  known  to  introduce  numerical  viscosity 
(Roache  1976),1  which  is  manifested  as  damping  of  a  signal.  The  slosh  test 
provides  a  means  of  examining  the  damping  of  a  particular  numerical 
computation  method.  In  a  slosh  test,  the  initial  condition  of  a  tilted  water  surface 
is  imposed,  and  the  basin  is  allowed  to  freely  propagate  the  resulting  wave 
through  reflection  at  both  ends.  External  forcing  and  bottom  frictional  stress  are 
set  to  zero  so  that  there  is  no  masking  of  the  free-surface  oscillations.  Time- 
series  of  water  elevation  over  the  duration  of  the  simulation  provides  information 
on  model  damping  properties.  Tests  described  here  were  patterned  after  those  by 
Cialone  (1989). 

The  slosh  test  was  performed  to  examine  damping  properties  and  mass 
conservation  for  two  grid  configurations.  Both  grid  configurations  were 
rectangular,  with  the  grid  being  longer  parallel  to  the  x-axis  than  parallel  to  the  y- 
axis.  A  test  consisted  of  applying  a  tilted  water  surface  as  the  initial  condition, 
where  the  direction  of  tilt  was  parallel  to  the  x-axis.  The  initial  deviation  from 
still-water  depth  was  symmetric  about  the  channel  center  and  increased  or 
decreased  sinusoidally  along  the  main  channel  axis  (Figure  Cl). 

No  variation  in  water  level  was  specified  across  the  width  (parallel  to  the  y- 
axis)  of  the  channel.  Initial  current  velocity  was  set  to  zero,  and  no  boundary 
forcing,  bottom  friction,  or  wind  stress  were  applied.  The  Coriolis  term  and 
lateral  mixing  were  set  to  zero.  Simulation  duration  was  set  to  30  days  (720  hr) 
and  the  time-step  was  set  to  5  s.  General  grid  configurations  and  inclusion  of 
advective  terms  are  given  in  Table  Cl.  Conducting  identical  tests  with  and 
without  inclusion  of  the  advective  terms  allows  isolation  of  their  contribution  to 
damping  and  mass  conservation. 


1  All  references  cited  in  this  appendix  are  included  in  the  References  section  at  the  end  of 
the  main  text. 
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Figure  Cl .  Slosh  test  initial  condition 

Table  Cl 

Slosh  Test  Configurations 

Test 

Bottom 

Advection 

1 

Flat 

No 

2 

Flat 

Yes 

3 

Sloped 

No 

4 

Sloped 

Yes 

Mass  conservation  was  calculated  as  percent  change  in  water  volume  over 
the  numerical  grid  between  time  t  =  0  and  the  end  of  the  simulation  period. 
Percent  change  in  water  volume  A¥-  was  calculated  as 


%AP  =  100 


f  n  n 

M _ i= ] _ 


in, 


i-\ 


(Cl) 


where  ¥y  is  the  final  volume,  +yc  is  the  initial  volume,  the  subscript  i  indicates 
cell  number,  and  n  is  the  total  number  of  cells  in  the  grid. 

Tests  1  and  2  were  conducted  to  evaluate  damping  and  mass  conservation  of 
the  model  for  a  flat-bottomed,  constant-spaced  grid,  with  and  without  the 
advective  terms  included  in  the  calculations,  respectively.  Grid  configurations 
and  numerical  parameters  for  Tests  1  and  2  are  given  in  Table  C2  and  the  grid  is 
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shown  in  Figure  C2.  Tests  1  and  2  resulted  in  5  x  10'6  and  1  x  10"5  percent 
changes  in  volume,  respectively. 


1  Table  C2 

Slosh  Test  Grid  Configurations  and  Numerical  Parameters  for 

J  Tests  1  and  2 

Numerical  Parameter 

Value 

As,  m 

500 

Af,  s 

5 

h,  m 

10 

Length,  m 

10,000 

Width,  m 

2,500 

L  =  10,000  m 


.  _ ’ _ 

500  m 

r 

1 

X 


Figure  C2.  Computational  grid  for  Tests  1  and  2 

Damping  properties  for  Tests  1  and  2  are  shown  by  time  series  of  water  level 
in  Figures  C3  and  C4,  respectively.  Water  levels  shown  for  each  plot  were  taken 
0.5Ax  from  the  boundary  and  centered  with  respect  to  channel  width.  Time 
series  shown  for  all  other  tests  are  also  taken  at  the  same  cell.  Axis  breaks  (x- 
axis)  were  inserted  into  the  plots  so  that  time  series  at  the  beginning  and  ending 
portions  of  the  simulations  could  be  easily  viewed.  Test  1  does  not  exhibit 
damping  over  the  duration  of  the  simulation.  Weak  nonlinear  motion  owes  to  the 
nonlinear  form  of  the  continuity  equation.  Test  2  exhibits  weak  damping  over 
the  1  -month  simulation.  Development  of  nonlinearities  is  slightly  stronger  than 
for  Test  1  owing  to  the  contribution  by  the  advective  terms.  Tests  1  and  2  were 
repeated  with  an  initial  surface  deviation  10  times  smaller  than  described  here 
(results  not  shown).  Motion  induced  by  this  smaller  water  surface  deviation  was 
not  sufficient  to  develop  nonlinearities  and  the  resulting  slosh  motion  for  both 
cases  (with  and  without  advection)  showed  no  variation  in  peak  water  level  and 
no  damping  was  exhibited. 
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The  fundamental  seiche  period  for  a  rectangular  basin  is  given  by 


T  = 


2/ 

■Jgh 


(C2) 


where  /  is  the  length  of  the  basin.  For  a  wave  traveling  parallel  to  the  x-axis  of 
the  slosh-test  grid,  T=  0.02337  day,  corresponding  to  a  frequency  of 
42.8  cycles/day  (cpd).  Spectrums  of  water  levels  shown  in  Figures  C3  and  C4 
for  Tests  1  and  2  are  displayed  in  Figures  C5  and  C6,  respectively.  Peak 
amplitudes  occur  at  42.8  cpd.  Small  peaks  (slightly  visible  in  Figures  C5  and 
C6)  are  contained  in  the  spectra  at  85.6  cpd,  indicating  the  presence  of  a  weak 
harmonic  of  the  primary  seiche  frequency.  These  tests  indicate  that  the 
discretized  equations  applied  for  calculation  of  water  level  in  Tests  1  and  2  do 
not  introduce  erroneous  frequencies  into  the  solution. 


Figure  C3.  Time  series  of  water  level  for  Test  1 


Figure  C4.  Time  series  of  water  level  for  Test  2 
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No  Advection 


c  2.5E-5 

i>T 

o 

I  2.0E-5 
a. 


Frequency,  cpd 


Figure  C5.  Spectrum  of  water  level  for  Test  1 


2.0E-5 

L 

a> 

|  1.5E-5 

a. 


Test  2 

With  Advection 


Frequency,  cpd 


Figure  C6.  Spectrum  of  water  level  for  Test  2 

Tests  3  and  4  were  designed  to  determine  how  damping  and  mass 
conservation  properties  respond  to  a  grid  with  sloped  bottom  and  constant  cell 
sizes.  Grid  configurations  and  numerical  parameters  for  Tests  3  and  4  are  given 
in  Table  C3  and  the  grid  is  shown  in  Figure  Cl.  Changes  in  volume  of  5  x  10'6 
and  1  x  10"5  percent  were  calculated  for  Tests  3  and  4,  respectively. 
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Table  C3 

Slosh  Test  Grid  Configurations  and  Numerical  Parameters  for 

Tests  3  and  4 

Numerical  Parameter 

Value 

As,  m 

500 

At,  s 

5 

h,  m 

Min  =  9  m,  Max  =  11  m,  Ah  I  Ax  =  0.0002 

Length,  m 

10,000 

Width,  m 

2,500 

L  =  10,000  m 


Figure  C7.  Computational  grid  for  Tests  3  and  4 

Damping  properties  for  Tests  3  and  4  are  shown  by  time  series  of  water  level 
in  Figures  C8  and  C9,  respectively.  Starting  maximum  water  level  for  both  Tests 
was  0.01  m  at  0.5 Ax  from  the  end  of  the  grid.  Test  3  does  not  exhibit  damping 
over  the  duration  of  the  simulation.  Water  levels  from  Test  4  are  slightly  damped 
by  properties  of  the  numerical  algorithm  for  the  advective  terms.  In  both  tests, 
water  levels  are  weakly  nonlinear,  as  described  for  Tests  1  and  2. 

Spectrums  of  water  levels  for  Tests  3  and  4  are  displayed  in  Figures  CIO  and 
Cl  1,  respectively.  Peak  amplitudes  occur  at  42.4  cpd.  Small  peaks  (slightly 
visible  in  Figures  C5  and  C6)  are  contained  in  the  spectra  at  84.8  cpd,  indicating 
the  presence  of  a  weak  harmonic  of  the  primary  seiche  frequency.  These  spectra 
demonstrate  that  the  discretized  equations  applied  for  calculation  of  water  level 
in  Tests  3  and  4  do  not  introduce  erroneous  frequencies  into  the  solution. 
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Figure  C8.  Time  series  of  water  level  for  Test  3 


Figure  C9.  Time  series  of  water  level  for  Test  4 
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Figure  CIO.  Spectrum  of  water  level  for  Test  3 


Figure  Cl  1 .  Spectrum  of  water  level  for  Test  4 
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Appendix  D 
Wind  Setup  Tests 


This  appendix  describes  tests  designed  to  evaluate  model  performance  under 
wind  forcing.  Two  tests  were  performed  to  examine  model  response.  The  first 
test  compares  the  results  of  numerical  calculations  to  those  of  an  analytical 
solution  for  a  rectangular  channel.  The  second  test  evaluates  model  response  to 
wind  forcing  in  a  basin  of  arbitrary  shape. 

Wind  setup  in  a  rectangular  channel  for  steady-state  conditions  is  maintained 
by  a  balance  of  the  pressure  gradient,  wind  forcing,  and  bottom  friction.  For  1-D 
flow,  the  momentum  equation  (Equation  2)  can  be  reduced  to  (Bretschneider 
1966)1 

dr i  =  (tw  +  t6)  pp 

dx  p  wg{h  + 1]) 


where  xw  is  the  wind  stress,  and  xb  is  the  bottom  stress.  In  the  absence  of 
bottom  friction,  Equation  D1  of  Bretschneider  can  be  rewritten  as 


dr |  k  IF2 
dx  g(h  +  r|) 


(D2) 


where  k  =  3.3  x  10~6 .  The  coefficient  k  was  derived  from  wind  and  bottom-stress 
coefficients  determined  in  a  study  of  Lake  Okeechobee,  FL  (Saville  1953). 
Application  of  Equation  D2  to  the  present  study  required  modification  of  k  to  be 
equal  to  the  wind-stress  coefficient  applied  in  M2D,  which  varies  with  wind 
speed,  so  that  analytical  and  numerical  solutions  could  be  compared.  Integration 
of  Equation  D2  gives 


r\  = 


(. x  +  C)  +  h 2 


-h 


(D3) 


1  All  references  cited  in  this  appendix  are  included  in  the  References  section  at  the  end  of 
the  main  text. 
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where  C  is  a  constant  of  integration  which  is  determined  by  the  position  of  the 
channel  origin  if  no  bottom  is  exposed,  and  by  the  position  of  the  water-land 
interface  if  drying  has  occurred.  The  parabolic  form  of  Equation  D3  indicates  a 
locally  wind-forced  water  surface  in  a  rectangular  channel  does  not  have  a  linear 
distribution  along  the  channel  axis.  Instead,  the  water  surface  will  be  curved, 
with  the  curvature  being  dependent  on  the  channel  length  and  depth,  and  the 
wind  speed. 

For  comparison  of  the  analytical  and  numerical  solutions  of  Equation  D2,  a 
1-D  grid  was  developed  that  had  a  total  length  of  9,500  m  and  was  95  cells  long. 
Each  square  cell  had  side  dimensions  of  100  m.  The  still-water  depth  was  set  to 
2  m  and  the  time-step  was  10  s.  The  wind  speed  set  to  10  m/s  and  held  constant. 
A  10-m/s  wind  speed  corresponds  to  k  =  1.9375  x  10“6 .  Figure  D1  compares 
water  level  computed  analytically  from  Equation  D2  and  numerically  by  M2D, 
under  steady-state  conditions.  The  numerical  solution  well  reproduces  the 
steady-state,  wind-induced  setup  and  setdown  of  the  analytical  solution  for 
simulations  applied  to  shallow  water. 


Distance,  m 


Figure  D1 .  Comparison  of  analytical  and  numerical  solutions  of  steady-state, 
wind-induced  setup,  no  exposed  channel  bottom 

To  test  the  response  of  the  model  to  wind  forcing  in  a  basin  of  arbitrary 
geometry,  a  modified  version  of  the  hourglass  test  developed  for  a  curvilinear 
grid  (Spaulding  1984)  was  examined.  An  hourglass-shaped  grid  was  developed 
with  constant  cell-side  lengths  set  to  500  m  and  an  ambient  depth  of  5  m.  The 
time-step  was  set  to  30  s.  Two  tests  were  performed,  one  for  wind  blowing  from 
the  west  (from  the  negative  x-axis)  and  the  other  for  wind  blowing  from  the  north 
(from  the  positive  y-axis).  For  each  test,  the  wind  was  ramped  up  over  a  24-hr 
interval  and  held  constant  at  10  m/s  for  the  remainder  of  the  100-hr  simulation. 


D2 
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Water  surface  elevation  for  the  west  wind  test  is  shown  in  Figure  D2.  The 
setup  and  setdown  are  symmetric  between  the  upper  and  lower  portions  of  the 
grid.  The  water  surface  elevation  contours  for  the  north  wind  test  are  shown  in 
Figure  D3.  The  water  surface  elevation  for  the  north  wind  test  is  equally 
distributed  between  the  left  and  right  portions  of  the  grid.  Symmetry  in  both  tests 
demonstrates  that  there  is  no  inconsistency  in  calculations  at  wall  boundaries. 

The  results  of  this  test  demonstrate  that  the  model  responds  to  wind  forcing  with 
qualitatively  correct  patterns  of  water  surface  deviation.  Wind  setup  calculated 
by  M2D  is  qualitatively  similar  to  results  displayed  graphically  by  Spaulding 
(1984)  and  by  Cialone  (1989). 


Figure  D2.  Water  surface  elevation  contours  for  west  wind 
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Appendix  E 
Advection  Test 


Advective  terms  were  examined  by  developing  a  grid  with  an  idealized 
jettied  inlet  and  displaying  the  current  field  during  ebb  flow.  Inclusion  of  the 
advective  terms  in  the  momentum  equations  allows  the  model  to  properly 
simulate  eddies  and  an  ebb  jet  as  the  ebb  flow  exits  the  inlet.  No  eddies  or  jet 
will  develop  without  advective  terms  included  in  the  calculations. 

The  idealized  inlet  grid  was  specified  to  have  a  flat  bottom  with  a  still-water 
depth  of  5  m.  Inlet  dimensions  were  300  m  wide  and  800  m  long.  Cell-side 
lengths  were  25  m  on  all  sides  in  the  inlet  and  nearshore  areas.  Cell  size 
increased  to  50  m  offshore.  The  time-step  was  set  to  1  s.  Water  level  was  forced 
with  a  sine  wave  having  amplitude  of  0.5  m  and  period  of  12.42  hr. 

Two  simulations  were  conducted,  one  without  advective  terms  included  in 
the  computations  and  one  with  them.  Figure  El  shows  the  current  field  from  the 
test  without  the  advective  terms  during  the  ebb  tidal  cycle.  No  eddies  are  present 
and  flow  exiting  the  inlet  spreads  laterally,  but  does  not  form  a  jet.  However, 
with  the  advective  terms  included  in  the  computations  (Figure  E2),  a  well- 
developed  ebb  jet  is  formed  and  eddies  are  present  on  each  side  of  the  jet.  The 
ebb  jet  and  eddies  are  symmetrical  about  the  axis  of  the  inlet,  demonstrating  that 
there  is  no  directional  bias  in  the  advection  algorithm. 
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Figure  El.  Ebb  current  field  for  advection  test:  no  advective  terms 


Figure  E2.  Ebb  current  field  for  advection  test:  with  advective  terms 
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Appendix  F 

Wetting  and  Drying  Tests 


Tests  were  performed  on  a  sloped-bottom  grid  to  determine  the  stability 
properties  of  the  wetting  and  drying  algorithms.  One-  and  two-dimensional  tests 
were  conducted  to  demonstrate  the  behavior  of  the  flooding  and  drying 
algorithms  under  different  sources  of  hydrodynamic  forcing  and  basin 
geometries.  A  list  and  brief  description  of  the  tests  are  given  in  Table  FI . 
Detailed  descriptions  and  model  results  are  provided  in  specific  test  sections  of 
this  appendix. 


Table  FI 

List  and  Description  of  Flooding  and  Drying  tests 

Test  Number 

Title 

Description 

1 

Channel  with  sloping 
bottom 

Test  wetting  and  drying  of  a  1-D  canal  forced  by  time- 
varying  wind. 

2 

Depression  in  a 
square  grid 

Test  stability  for  wetting  dry  cells  surrounding  a 
ponded  area.  2-D  grid. 

Testl:  Channel  with  Sloping  Bottom 

A  one-dimensional  (ID)  test  was  conducted  to  examine  the  flooding  and 
drying  algorithms  for  a  channel  with  simple  geometry.  The  test  consisted  of  a 
channel  with  a  sloping  bottom  that  was  forced  by  a  time-varying  wind.  The 
channel  length  was  150,000  m  with  101  cells  along  the  main  channel  axis 
(parallel  to  the  x-axis)  and  1  grid-cell  wide.  Cells  were  square  with  side  lengths 
of  1,500  m.  The  time-step  was  100  s.  The  bottom  slope  of  the  channel  was 

1.67  x  10“5  with  a  maximum  still-water  depth  of  3  m  and  a  minimum  still- water 
depth  of  0.5  m.  Forcing  for  the  test  consisted  of  a  wind  that  blew  along  the 
channel  from  the  shallow  end  toward  the  deep  end.  The  wind  was  ramped  up 
over  10  hr  to  a  maximum  speed  of  10  m/s  and  held  constant  from  hour  10  to  hour 
100.  The  wind  was  turned  off  at  101  hr  and  remained  off  for  the  remainder  of  the 
200-hr  simulation. 

Time  series  of  water  elevation  for  the  sloping-bottom  test  are  shown  in 
Figure  FI  in  10-hr  intervals.  Twenty-six  cells  on  the  shallow  end  of  the  grid  are 
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Figure  FI .  Demonstration  of  flooding  and  drying  of  sloped  channel 
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shown  out  of  the  101  cells  in  the  grid.  Ambient  water  depths  in  the  channel 
increase  from  left  to  right.  Dry  cells  are  shown  as  white.  Over  the  duration  the 
wind  stress  applied  to  the  channel  (0  to  100  hr),  water  is  forced  out  of  the  shallow 
area  so  that  successive  drying  of  cells  occurs  from  left  to  right.  A  maximum  of 
21  cells  dried  during  the  simulation.  After  the  wind  was  turned  off  (hour  101), 
water  flows  from  right  to  left,  successively  inundating  the  dry  cells. 


Test  2:  Depression  in  Square  Grid 

A  source  of  instability  in  some  flooding  and  drying  algorithms  is  rewetting  of 
dry  cells  that  surround  an  area  that  has  formed  a  pond.  A  robust  flooding 
algorithm  will  remain  stable  with  any  pattern  of  wet  and  dry  cells.  This  test  was 
designed  to  determine  the  behavior  of  the  wetting  and  drying  algorithms  where 
ponding  takes  place. 

A  square  grid  consisting  of  400  50  x  50-m  cells  was  developed  in  which  the 
central  area  contained  a  square  ring  of  shallow  cells  surrounding  deeper  cells 
(Figure  F2).  Outside  the  shallow  ring,  the  depth  was  set  to  2  m  everywhere. 

Cells  in  the  shallow  ring  were  specified  with  depths  of  0.3  m,  with  adjacent 
interior  cells  having  depths  of  0.5  m,  and  adjacent  outer  cells  having  depths  of 
1.0  m.  Four  cells  in  the  center  of  the  depression  were  1-m  deep. 


Figure  F2.  Grid  with  central  depression  surrounded  by  shallow  area 
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The  grid  was  forced  with  water  surface  elevation  at  six  cells  located  on  the 
left  side  of  the  grid,  denoted  by  the  red  line  in  Figure  F2.  A  sinusoidal  forcing 
was  applied  having  amplitude  of  1  m  and  period  of  12  hr.  The  depth  at  which 
cells  are  deemed  dry  was  specified  as  0.05  m.  The  model  was  run  for  duration  of 
50  hr,  with  a  ramp  of  1  day  and  time-step  of  5  s.Plots  of  water  level  and 
circulation  are  shown  in  Figures  F3  through  F10  at  hourly  intervals  starting  at 
hour  42.  During  hours  43  to  47,  the  water  level  was  lowered  to  expose  the  ring 
of  shallow  cells.  The  dry  cells  are  denoted  by  white  with  no  current  vectors.  A 
pond  was  formed  within  the  interior  of  the  ring  of  dry  cells. 

Water  level  rises  from  hours  45  through  49.  At  hour  46  (Figure  F7),  cells  on 
the  outer  portion  of  the  shallow  ring  (with  ambient  depths  of  1  m)  have  rewetted. 
By  hour  48  (Figure  F9),  all  previously  dry  cells  have  rewetted.  During  the 
process  of  flooding  and  drying,  no  instabilities  were  encountered.  Thus,  the 
wetting  and  drying  algorithms  in  M2D  function  properly  for  the  situation  of 
flooding  around  a  ponded  area. 


Figure  F3.  Water  level  and  circulation  pattern  at  hour  42 
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Figure  F6.  Water  level  and  circulation  pattern  at  hour  45 


Figure  F 7.  Water  level  and  circulation  pattern  at  hour  46 


F6 


Appendix  F  Wetting  and  Drying  Tests 


Appendix  G 

Wave-Adjusted  Boundary 
Condition  Test 


This  appendix  demonstrates  the  wave-adjusted  boundary  condition  for  an 
idealized  beach.  In  the  example,  wave  forcing  is  applied  to  calculate  an 
alongshore  current.  The  wave-adjusted  boundary  condition  modifies  the  water 
level  and  velocity  on  boundaries  forced  by  water  surface  elevation  to  account  for 
the  presence  of  wave  forcing.  Thus,  the  prescribed  boundary  forcing  is  applied 
after  being  adjusted  for  the  presence  of  waves.  This  adjustment  promotes 
realistic  circulation  patterns  and  wave  setup  and  setdown  at  the  boundaries, 
making  values  at  the  lateral  boundaries  compatible  with  values  calculated  within 
the  calculation  domain  near  the  boundaries.  A  simulation  without  the  wave- 
adjusted  boundary  condition  is  also  shown,  which  illustrates  the  necessity  of  the 
modification  of  water  level  and  velocity  at  the  boundary. 

An  idealized  beach  computational  grid  was  developed  (Figure  Gl)  having 
grid  spacing  of  50  m  in  each  horizontal  direction,  and  depths  ranging  from 
1 .13  m  at  the  shoreline  to  18.4  m  at  the  seaward  boundary.  M2D  and  STWAVE 
domains  were  identical  for  the  idealized  beach  simulations. 

Forcing  for  the  models  was  specified  as: 

a.  STWAVE:  Wave  height  of  2.0  m,  period  of  10.0  s,  and  wave  angle  of 
25.0  deg.  Spectral  spreading  parameters  were  y  =  3.3  and  nn  =  4. 

b.  M2D:  Water  surface  elevation  set  to  0.0  m  along  lateral  and  seaward 
boundaries. 

M2D  was  run  for  12.5  hr  with  a  2-s  time-step  and  ramp  duration  of  0.02  day. 
Results  from  the  simulation  without  the  wave-adjusted  boundary  condition  are 
described  first,  followed  by  those  with  the  wave-adjusted  boundary  condition. 
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Figure  G1.  Computational  grid  for  idealized  beach 


Water  surface  elevation  and  velocity  as  computed  by  the  standard  water 
surface  elevation  forcing  boundary  condition  (boundaries  not  adjusted  for 
presence  of  wave  forcing)  are  shown  in  Figures  G2  and  G3,  respectively.  Setup 
is  calculated  at  the  shoreline,  but  decreases  to  zero  at  the  lateral  boundaries.  An 
alongshore  current  is  develops  in  the  nearshore  area,  but  velocities  at  the  lateral 
boundaries  are  weaker  than  inside  the  calculation  domain  and  display  unrealistic 
patterns.  The  unrealistic  velocity  patterns  and  water  surface  elevations  at  the 
lateral  boundaries  owe  to  the  absence  of  the  wave  stresses  there. 
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Figure  G2.  Water  surface  elevation  calculated  with  standard  water 
surface  elevation  boundary  condition 


Figure  G3.  Velocity  calculated  with  standard  water  surface  elevation  boundary 
condition 
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Water  surface  elevation  and  velocity  as  computed  by  the  wave-adjusted 
boundary  condition  are  shown  in  Figures  G4  and  G5,  respectively.  Setup  is 
calculated  at  the  shoreline  and  extends  nearly  uniformly  across  the  entire  grid. 
An  alongshore  current  is  well  developed  in  the  nearshore  area,  both  near  the 
lateral  boundaries  and  away  from  them.  Because  the  boundary  conditions  were 
adjusted  for  the  presence  of  wave  forcing,  the  circulation  patterns  are  realistic. 
Water  can  flow  onto  and  off  of  the  grid  along  the  lateral  boundaries  without 
incompatibility  between  the  boundary  condition  and  interior  hydrodynamic 
processes. 


Figure  G4.  Water  surface  elevation  calculated  with  wave-adjusted  boundary 
condition 
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Figure  G5.  Velocity  calculated  with  wave-adjusted  boundary  condition 
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Appendix  H 

Surf  Zone  Verification  Tests 


To  verify  M2D’s  response  to  wave  forcing,  calculations  were  compared  to 
laboratory  data  collected  by  Visser  (1982). 1  Because  the  laboratory  experiments 
were  conducted  with  monochromatic  waves  and  the  bathymetry  was  uniform 
alongshore,  M2D  was  modified  to  include  a  1-D  monochromatic  wave- 
transformation  model.  This  model  applies  linear  wave  theory  to  compute  wave 
transformation  and  computes  wave  height  of  depth-limited  breaking  and  broken 
waves  by  the  wave  stability  relationship  of  Dally  et  al.(l  985).  It  also  includes 
representation  of  the  wave  roller  as  described  by  Dally  and  Brown  (1995)  and 
Dally  and  Osiecki  (1994).  Water  levels  calculated  by  M2D  are  passed  to  the 
wave  transformation  model  to  allow  waves  to  respond  to  the  setup  and  setdown. 

Larson  and  Kraus  (2002)  provide  succinct  descriptions  of  the  wave  stability 
relationship  and  roller  model  together  with  comparisons  of  calculated  and 
measured  longshore  current,  including  comparisons  to  the  Visser  (1982)  data, 
with  and  without  the  roller  model.  Their  results  demonstrate  that  inclusion  of  the 
roller  momentum  for  calculation  of  the  longshore  current  and  wave  setup 
increases  accuracy.  Without  the  roller  momentum,  peak  longshore  current  was 
calculated  to  be  seaward  of  the  measured  peak,  whereas  including  the  roller 
shifted  the  peak  toward  the  beach  and  generally  aligned  it  with  the  measured 
peak.  This  adjustment  of  the  cross-shore  distribution  of  the  longshore  current 
modified  the  setup  with  an  increased  setup  with  the  roller  as  compared  to  without 
it. 


Calculation  of  longshore  current  and  setup  are  conducted  for  two  of  the 
Visser  (1982)  data  sets,  Cases  4  and  7.  Wave  properties  for  each  case  are  listed 
in  Table  HI,  and  cross-shore  profiles  and  roughness  information  are  listed  in 
Table  H2.  The  major  difference  between  these  two  cases  is  the  bottom 
roughness.  Case  4  was  run  on  a  smooth  concrete  bottom,  whereas  bottom 
roughness  elements  were  introduced  for  Case  7,  with  the  wave  conditions  held  to 
be  the  same  as  much  as  possible.  By  choosing  these  two  tests,  performance  of 
M2D  in  the  surf  zone  over  a  great  difference  in  bottom  roughness  can  be 
demonstrated. 


1  All  references  cited  in  this  appendix  are  included  in  the  References  section  at  the  end  of 
the  main  text. 
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Table  HI 

Wave  Properties  at  Offshore  End  of  Basin  and  Breaker  to  Depth 
Ratio  for  Selected  Visser  (1982)  Laboratory  Experiments 


Case 

Wave  Height,  m 

Wave  Period,  s 

Wave  Angle,  deg 

Breaker  to  Depth 
Ratio 

4 

0.076 

1.02 

19.9 

0.83 

7 

0.078 

1.02 

18.4 

0.74 

Table  H2 

Cross-Shore  Profiles  and  Roughness  Information  for  Selected 
Visser  (1982)  Laboratory  Experiments 

Case 

Distance  Across 
Shore,  m 

Depth,  m 

Beach  Slope1 

Bottom 

Roughness  | 

4 

-0.472 

-0.040 

0.050 

smooth 

7.328 

0.350 

8.253 

0.350 

7 

-0.472 

-0.040 

0.050 

rough 

7.328 

0.350 

9.503 

0.350 

11  il 

1  Beach  slope  calculated  for  sloping  portion  of  basin. 


Computational  grids  were  developed  for  each  bathymetric  profile,  and  depths 
were  uniform  alongshore.  For  each  grid,  the  cell  spacing  parallel  with  the 
alongshore  direction  (Ay )  was  0.10  m.  Cell  spacing  parallel  with  the  cross¬ 
shore  direction  (Ax)  was  0.01  m  from  the  offshore  boundary  to  approximately 
1  m  from  the  shoreline.  Resolution  was  increased  nearer  to  the  shore  to  capture 
details  of  the  setup  calculation.  As  an  example,  resolution  change  for  the  Case  7 
computational  grid  is  shown  in  Figure  HI. 

Simulations  were  conducted  with  identical  parameter  settings  and  time-step, 
with  the  exception  of  the  Manning  roughness  coefficient  and  the  breaker-to-depth 
ratio  for  which  settings  were  case  dependent.  The  depth  at  which  cells  were 
specified  as  dry  was  0.001  m  and  the  time-step  was  0.025  s.  Breaker-to-depth 
ratios  for  each  case  are  provided  in  Table  HI.  The  Manning  roughness 
coefficient,  serving  as  an  adjustment  parameter,  was  set  to  0.0125  for  Case  4  and 
to  0.022  for  Case  7,  after  numerical  experimentation.  Wave  calculations 
proceeded  shoreward  until  a  minimum  wave  height  of  0.001  m  was  reached. 


H2 
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Figure  HI .  Detail  of  computational  grid  for  Case  7  showing  cross-shore  variation 
in  cell  spacing 


Comparison  of  measurements  and  calculations  for  wave  height,  longshore 
current  speed,  and  setup  for  Case  4  are  shown  in  Figures  H2,  H3,  and  H4, 
respectively.  Calculated  wave  height  compared  well  with  measurements,  except 
for  the  maximum  wave  height,  which  was  underestimated  by  the  wave- 
transformation  model.  The  calculated  breakpoint  took  place  directly  shoreward 
and  nearly  at  the  measured  location. 

Calculated  longshore  current  speed  well  reproduced  the  distribution 
determined  by  the  measurements  (Figure  H3).  Peak  current  speeds  compare 
well,  with  the  calculated  peak  located  directly  seaward  of  the  measured  peak. 
Seaward  of  the  breakpoint,  calculated  weakening  of  the  longshore  current  closely 
follows  the  measured  reduction  in  current. 

Setup  calculations  also  compare  favorably  to  the  measurements  (Figure  H4). 
The  slope  of  the  setup  is  slightly  reduced  in  the  calculations  as  compared  to 
measurements,  but  the  overall  result  indicates  that  the  model  is  reproducing  the 
wave-induced  setup. 

Comparison  of  calculated  and  measured  wave  height  and  longshore  current 
speed  for  Case  7  (artificial  roughness)  are  shown  in  Figures  H5  and  H6, 
respectively,  and  calculated  setup  is  shown  in  Figure  H7  (setup  measurements  are 
not  available  for  Case  7).  Calculated  peak  wave  height  underpredicts  the 
measured  peak  wave  height.  However,  because  measured  wave  heights  before 
breaking  are  not  available,  there  is  no  indication  of  whether  strong  nonlinear 
shoaling  took  place.  Calculated  longshore  current  speed  closely  matches 
measurements  over  the  peak  and  offshore  reduction  in  speed. 
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Longshore  Current  Speed,  m/s  |  [  Wave  Height, 


H2.  Wave  height  comparison  for  Case  4 


Figure  H3.  Longshore  current  comparison  for  Case  4 
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Wave  Height,  m  |  cl  Setup, 


H4.  Wave-induced  setup  comparison  for  Case  4 


Figure  H5.  Wave  height  calculated  by  roller  model  for  Case  7 
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Figure  H6.  Longshore  current  calculated  by  M2D  for  Case  7 


Figure  H7.  Wave-induced  setup  calculated  by  M2D  for  Case  7 


In  conclusion,  calculations  with  M2D  well  reproduced  the  qualitative  and 
quantitative  features  of  accurate  measurements  of  the  longshore  current  in  the 
laboratory.  This  test  validates  the  overall  equation  solution  scheme  of  the  model 
and  contributions  of  several  terms,  including  the  radiation  stresses,  bottom 
friction,  and  mixing. 
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large-scale  applications  and  connectivity  between  models. 

A  graphical  interface  for  M2D  has  been  implemented  within  the  Surface-Water  Modeling  System  (SMS)  Versions  8.1  and  higher. 
Features  of  the  M2D  interface  are  grid  development,  control  file  specification,  model  runs,  post-processing  of  results,  and  visualization. 
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M2D  can  be  driven  by  larger-domain  circulation  models,  such  as  ADCIRC,  through  boundary  specification 
capabilities  contained  within  the  SMS.  The  Steering  Module  in  SMS  provides  an  automated  means  of  coupling  of 
M2D  with  STWAVE,  which  is  convenient  for  projects  that  require  wave-stress  forcing  for  M2D  as  well  as  wave 
friction  and  mixing  owing  to  breaking  waves.  The  Steering  Module  allows  the  user  to  choose  from  seven  possible 
coupling  combinations,  providing  flexibility  in  conducting  simulations  of  wave-driven  currents  and  wave-current 
interaction. 


